API 오류는 표준 HTTP 상태 코드와 응답 본문의 JSON 오류 개체를 통해 좀 더 자세한 내용을 표시한다. 일반적으로 클라이언트 오류는 HTTP 상태 코드 400번대, 서버 오류는 500번대로 표시된다.
자세한 오류 내용을 제공하는 경우 응답 본문에 다음과 같은 형식으로 표시된다.
{ "code": "ERROR_CODE", "description": "error description"}일반적으로 제공되는 오류 코드는 다음과 같다.
| HTTP Status Code | Code | Description |
|---|---|---|
| 400 | BAD_REQUEST | 클라이언트 요청의 형식이나 내용이 잘못되어 서버가 처리할 수 없는 경우 |
| 400 | INVALID_PARAMETER | 클라이언트에서 요청한 파라미터의 형식이나 내용에 오류가 있는 경우 |
| 400 | INVALID_{RESOURCE} | 클라이언트에서 요청한 리소스의 내용에 오류가 있는 경우 |
| 400 | MISSING_PARAMETER | 필수 파라미터를 지정하지 않은 경우 |
| 400 | LIMIT_EXCEEDED | 파라미터 혹은 리소스 속성값의 제한 설정을 초과하는 경우 |
| 400 | OUT_OF_RANGE | 파라미터 혹은 리소스 속성값의 범위를 벗어나는 경우 |
| 401 | UNAUTHORIZED | 요구되는 인증 정보를 누락하거나 잘못 지정해 요청한 경우. 일반적인 인증 오류는 RFC 6749에 정의된 내용을 표시한다. |
| 403 | FORBIDDEN | 서버가 클라이언트의 요청을 이해했으나 거부하는 경우. 클라이언트 앱이 접근하려는 리소스에 대한 접근 권한이나 OAuth scope를 가지고 있지 않으면 접근이 거부된다. |
| 403 | ACCESS_DENIED | 클라이언트가 요청하는 리소스에 대한 접근이 제한되는 경우 |
| 403 | LIMIT_EXCEEDED | 클라이언트가 요청하는 리소스의 제한 설정을 초과하는 경우 |
| 403 | OUT_OF_RANGE | 클라이언트가 요청하는 리소스의 제한 범위를 벗어나는 경우 |
| 404 | NOT_FOUND | 클라이언트가 요청하는 리소스를 찾을 수 없는 경우 |
| 404 | {RESOURCE}_NOT_EXIST | 클라이언트가 요청하는 특정 리소스를 찾을 수 없는 경우 |
| 409 | CONFLICT | 클라이언트가 요청하는 리소스와 충돌이 발생하는 경우 |
| 409 | ALREADY_EXIST | 클라이언트가 요청하는 리소스가 이미 존재하는 경우 |
| 409 | {RESOURCE}_ALREADY_EXIST | 클라이언트가 요청하는 특정 리소스가 이미 존재하는 경우 |
| 410 | DELETED | 클라이언트가 요청하는 리소스가 이미 삭제되어 서버에 존재하지 않는 경우 |
| 500 | INTERNAL_SERVER_ERROR | 특정할 수 없는 서버의 내부 오류 |
| 503 | SERVICE_UNAVAILABLE | 일시적인 서버 오류 |
API 요청 시 Header에 지정한 Access Token이 잘못된 경우, www-authenticate 응답 헤더를 통해 오류가 발생한 원인을 확인할 수 있다. RFC 6750 에 정의된 내용을 표시한다.
www-authenticate 헤더의 구조는 아래와 같다.
www-authenticate {auth-scheme} {auth-param}, {auth-param}...| HTTP Status Code | www-authenticate | 오류 발생 케이스 |
|---|---|---|
| 400 | www-authenticate: Bearer error="invalid_request" | 요청한 파라미터 형식이 잘못된 경우 |
| 401 | www-authenticate: Bearer error="invalid_token" | Access Token이 잘못된 경우 |
| 403 | www-authenticate: Bearer error="insufficient_scope", scope="{scope list}" | Access Token이 API를 호출하기 위한 Scope 권한이 없는 경우 |
참고
www-authenticate 헤더는 모든 오류 케이스에 응답하지 않는다. HTTP Status Code가 400, 401 혹은 403일때 특정한 케이스에서만 포함되는 응답 정보임을 참고한다.