에러 처리 - Tiro Docs

에러 응답 형식

모든 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로 재시도하세요)

​에러 응답 형식

​필드

​HTTP 상태 코드 & 에러 타입

에러 응답 형식

필드

HTTP 상태 코드 & 에러 타입