에러 응답 형식
모든 Tiro API 에러는 일관된 JSON 구조를 따라요.{
"error": {
"code": 400001,
"errorType": "bad_request",
"message": "Human readable error message",
"detail": "Additional context or null"
}
}
필드
| 필드 | 타입 | 설명 |
|---|---|---|
code | integer | AAABBB 형태의 6자리 에러 코드예요. 앞 3자리는 HTTP 상태와 일치하고, 뒤 3자리는 상태별 일련번호예요. 세밀한 클라이언트 분기에 사용하세요. |
errorType | string | HTTP 상태에서 파생된 큰 범주의 분류예요. 시간이 지나도 안정적이라 클라이언트 분기에 안전해요. 아래 표를 참고하세요. |
message | string | 사람이 읽을 수 있는 에러 메시지예요. 안정적이지 않으니 분기에 사용하지 마세요. |
detail | object | string | null | 선택적인 추가 정보예요 (에러마다 달라요). |
HTTP 상태 코드 & 에러 타입
| 상태 | errorType | 의미 |
|---|---|---|
| 400 | bad_request | 잘못된 요청 형식 또는 파라미터 |
| 401 | unauthorized | API 키 누락 또는 무효 |
| 403 | forbidden | API 키에 필요한 권한 없음 |
| 404 | not_found | 리소스가 존재하지 않음 |
| 406 | not_acceptable | 지원하지 않는 Accept 헤더 |
| 409 | conflict | 리소스가 이미 존재하거나 상태 충돌 |
| 413 | payload_too_large | 요청 본문이 크기 제한 초과 |
| 422 | unprocessable_entity | 형식은 유효하지만 데이터가 유효하지 않음 |
| 429 | too_many_requests | rate limit 초과 |
| 5xx | internal_error | 서버 측 에러 (더 파싱하지 말고 backoff로 재시도하세요) |