에러 처리
에러는 적절한 HTTP 상태 코드와 함께 일관된 JSON 구조로 반환됩니다.
{
"error": {
"type": "invalid_request_error",
"code": "missing_parameter",
"message": "title은 필수입니다.",
"param": "title"
}
}| 필드 | 설명 |
|---|---|
type |
에러 분류 (아래 표) |
code |
기계가 분기하기 위한 세부 코드 |
message |
사람이 읽는 설명 (그대로 노출하지 말고 분기엔 code 사용) |
param |
문제가 된 입력 필드 (있을 때) |
에러 분류
| type | HTTP | 의미 |
|---|---|---|
authentication_error |
401 | 키 누락·무효 |
permission_error |
403 | 권한 부족 |
invalid_request_error |
400 | 잘못된 파라미터 |
not_found_error |
404 | 자원 없음 |
conflict_error |
409 | 상태 충돌(예: 이미 발송됨) |
rate_limit_error |
429 | 요청 제한 초과 |
api_error |
5xx | 서버 측 오류 |
권장 처리
429·5xx는 지수 백오프로 재시도하세요.4xx(429 제외)는 재시도해도 동일하게 실패합니다.code로 분기하세요.
전체 코드 목록은 에러 코드 표를 참고하세요.