에러 처리

모든 에러 응답은 같은 형태입니다 — OpenAI 스타일 슈퍼셋. type+code는 변하지 않는 머신 값이므로 분기에 사용하세요. message는 사람이 읽는 용도이며 바뀔 수 있습니다. param은 문제가 된 필드명(있을 때, 없으면 null).

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_error",
    "message": "template is invalid",
    "param": "template",
    "retryable": false
  }
}

AI Engine API와 하나의 핸들러로

AI Engine API(api.atrace.ai)도 type·code·message·param을 공유하므로, 두 API를 error.type+error.code 기준 하나의 에러 핸들러로 처리할 수 있습니다. 단, AI Engine의 **인증 실패(401)**는 게이트웨이가 { "message": "...", "request_id": "..." } 형태로 응답해 다릅니다. 자세한 차이는 Report API와 AI Engine API를 보세요.

상태 코드

HTTP	type	code	의미	retryable
`401`	`authentication_error`	`unauthorized`	인증 실패 (키 없음/무효)	아니오
`403`	`permission_error`	`forbidden`	스코프 초과 (권한 없는 호출)	아니오
`404`	`invalid_request_error`	`not_found`	리소스 없음	아니오
`409`	`invalid_request_error`	`idempotency_conflict`	멱등 키 충돌 (같은 `Idempotency-Key`, 다른 본문)	아니오
`409`	`invalid_request_error`	`slot_already_succeeded`	이미 성공한 슬롯 재등록	아니오
`422`	`invalid_request_error`	`validation_error`	검증 실패 (필드 오류)	아니오
`429`	`rate_limit_error`	`rate_limited`	게이트웨이에서 일시적으로 요청이 거부됨 (현재 고정 한도는 강제하지 않으나 게이트웨이에서 발생 가능)	예 (지수 백오프)
`5xx`	`api_error`	`internal_error`	서버 오류	예 (지수 백오프)

retryable: true인 경우에만 재시도하세요. 재시도할 때 Idempotency-Key를 그대로 유지하면 중복 생성을 막습니다.

부분 실패는 에러가 아닙니다

일부 슬롯만 실패하는 경우는 HTTP 에러가 아니라 리포트 상태로 나타납니다. GET /reports/{id}의 슬롯별 status와 리포트 summary_status를 확인하세요.

{
  "summary_status": "partial",
  "slots": [
    { "module_type": "tire", "slot": { "position": "front_left", "image_type": "tread" }, "required": true, "status": "success" },
    { "module_type": "tire", "slot": { "position": "rear_right", "image_type": "tread" }, "required": true, "status": "failed" }
  ]
}

실패한 슬롯은 POST /reports/{id}/analyze로 재분석하거나, 이미지를 다시 등록(?replace=true)할 수 있습니다.

상태 코드

부분 실패는 에러가 아닙니다

다음 단계

Rate limits

ATRACE Report API 레퍼런스

On this page