서문
Odoo REST API 오류는 클라이언트가 Odoo의 REST 엔드포인트로 보낸 HTTP 요청이 실패할 때 발생합니다. Odoo는 기본적으로 XML-RPC와 JSON-RPC를 제공하지만, 실제 운영 환경에서는 컨트롤러 위에 직접 만든 REST 엔드포인트를 많이 사용합니다.
REST API 오류는 다음 환경에서 특히 잦습니다:
- 헤드리스 Odoo 구성(프론트엔드와 분리된 백엔드)
- 이커머스 플랫폼 연동
- 모바일 앱 연동
- 외부 SaaS나 마켓플레이스와의 연결
- 미들웨어(ESB) 기반 통합 시나리오
UI에서 보이는 오류와 달리, REST API 오류는 보통 다음과 같은 HTTP 상태 코드 형태로 표시됩니다:
- 400 (잘못된 요청)
- 401 (인증 필요)
- 403 (권한 없음)
- 404 (찾을 수 없음)
- 500 (서버 내부 오류)
이 가이드는 Odoo에서 REST API 오류가 발생하는 이유를 설명하고, 문제 원인 진단과 올바른 해결 방법을 제시합니다.
Odoo에서 말하는 REST API란 무엇인가
Odoo에서 REST API는 보통 컨트롤러 방식으로 구현됩니다:
from odoo import http
from odoo.http import request
class MyController(http.Controller):
@http.route('/api/order', type='json', auth='user', methods=['POST'])
def create_order(self, **kwargs):
# logic here
return {"status": "success"}
REST API가 정상 동작하려면 여러 요소가 함께 맞아야 합니다:
- HTTP 메서드(GET, POST, PUT, DELETE) 규약
- 인증 및 권한 처리 방식
- JSON 형태의 페이로드
- 올바른 라우팅(경로 설정)
이 중 어느 하나라도 틀어지면 Odoo는 REST API 오류를 반환합니다.
Odoo REST API 오류가 자주 발생하는 이유
1. 인증 실패 (401 Unauthorized)
인증 정보가 없거나 잘못되면 Odoo는 다음과 같은 응답을 보냅니다:
401 Unauthorized
주요 원인:
- API 토큰 누락
- 잘못된 자격 증명
- 만료된 세션
- 잘못된 인증 방식 사용
2. 권한 거부 (403 Forbidden)
사용자 인증은 되었지만 요청한 작업에 대한 권한이 없을 때:
403 Forbidden
주로 다음 상황을 의미합니다:
- 접근 권한 설정 누락
- 그룹 권한 설정 오류
- 레코드 규칙이 제한함
3. 잘못된 엔드포인트 (404 Not Found)
정의된 라우트가 없을 경우:
404 Not Found
가능한 원인:
- 잘못된 URL
- 모듈이 설치되지 않음
- 라우트 설정 오류
- 요청한 HTTP 메서드가 다름
4. 잘못된 페이로드 (400 Bad Request)
JSON 바디가 형식에 맞지 않거나 필수 데이터가 없을 때:
400 Bad Request
예시:
- 필수 필드 누락
- 잘못된 데이터 타입
- 관계형 ID가 유효하지 않음
5. 백엔드 예외 (500 Internal Server Error)
컨트롤러 내부 로직에서 예외가 발생하면:
500 Internal Server Error
REST API 실패 중에서 가장 빈번한 유형입니다.
자주 발생하는 원인:
- 처리되지 않은 파이썬 예외
- 데이터베이스 제약 위반
- 잘못된 관계 참조
- 필수 값 누락
6. CSRF 토큰 문제
라우트에 csrf=True가 설정되어 있고 유효한 CSRF 토큰이 없으면 요청이 실패합니다.
일반적으로 API 엔드포인트는 csrf=False로 설정해야 합니다.
Odoo REST API 오류 해결 방법
1단계 – HTTP 상태 코드 확인
상태 코드는 문제 유형을 파악하는 첫 단서입니다:
- 400 → 페이로드 문제 가능성
- 401 → 인증 문제
- 403 → 권한 문제
- 404 → 라우트 또는 URL 문제
- 500 → 서버 내부 예외
2단계 – 라우트(경로) 설정 검증
다음 항목들을 점검하세요:
@http.route('/api/order', type='json', auth='user', methods=['POST'])
확인 사항:
- URL 경로가 정확한가?
- 요청에 사용된 HTTP 메서드와 일치하는가?
- auth 설정이 요구사항에 맞는가?
- CSRF 설정이 적절한가?
3단계 – 인증 방식 확인
다음 사항을 확인하세요:
- API 토큰이 유효한가?
- 세션 쿠키가 살아있는가?
- auth='user'나 auth='public' 같은 인증 타입이 맞는가?
운영 환경에서는 통합 전용 계정을 사용하는 것이 안전합니다.
4단계 – 요청 전 페이로드 유효성 검증
요청을 보내기 전에 다음을 점검하세요:
- 필수 필드를 모두 포함했는가?
- 관계형 ID가 존재하는가?
- 데이터 타입이 올바른가?
- 필수 필드에 null이 들어가 있지 않은가?
입력 데이터를 미리 검증하면 REST API 오류를 크게 줄일 수 있습니다.
5단계 – 500 오류는 서버 로그에서 원인 확인
응답이 500이면 Odoo 서버 로그를 확인하세요.
특히 찾아볼 것:
Traceback (most recent call last):
트레이스백은 실제 원인 파악에 결정적입니다.
6단계 – 컨트롤러에 적절한 예외 처리 도입
날것의 예외를 그대로 노출하는 대신,
try:
# logic
except Exception as e:
return {"error": str(e)}
구조화된 오류 응답은 통합 안정성을 높입니다.
Odoo REST API 오류 예방 방법
- 전용 API 사용자 사용
- Odoo로 요청을 보내기 전 입력 검증 레이어 두기
- 명확한 예외 처리 로직 구현
- 컨트롤러에 무거운 비즈니스 로직을 넣지 않기
- 대량 작업은 배치로 처리하기
- 요청과 응답을 로깅하여 문제 재현에 유리하게 만들기
외부 시스템과 Odoo 사이에 검증·변환 레이어를 두면 REST API 실패를 획기적으로 줄일 수 있습니다.
다솔로(Dasolo)가 안정적인 REST 통합을 설계하는 법
Odoo에서 REST API 오류는 대개 인증 헤더 불일치, 컨트롤러 설정 오류, 또는 부적절한 요청 처리에서 옵니다. REST 엔드포인트는 외부에 노출되는 경우가 많아 작은 검증 누락도 반복적인 실패로 이어집니다.
다솔로에서는 REST 통합을 안정화하기 위해 다음에 집중합니다:
- 보안성 높은 토큰 기반 인증 구성
- 명확하고 단순한 컨트롤러 로직
- 요청/응답의 엄격한 유효성 검사
- 권한 범위(스코핑)를 명확히 정의
- 외부 호출에 대한 구조화된 로깅
이러한 규율 있는 REST 아키텍처는 통합 불안정을 줄이고 시스템의 장기적 탄력성을 높입니다.
맺음말
Odoo의 “REST API 오류”는 보통 인증 실패, 잘못된 페이로드 구조, 권한 충돌, 또는 처리되지 않은 백엔드 예외 때문에 발생합니다. 기술적인 에러처럼 보이나, 대부분 엔드포인트 설정이나 입력 검증 로직의 취약점을 드러냅니다.
컨트롤러 구현을 검토하고 인증 흐름을 안전하게 하며 일관된 오류 처리를 도입하면 반복적인 REST API 장애를 크게 줄일 수 있습니다. 튼튼한 통합 레이어가 구축되면 Odoo와 외부 애플리케이션 간 통신의 신뢰성이 오래도록 유지됩니다.