X-Request-Id 헤더가 포함되며,
요청을 디버깅하는 데 필요한 정보만 반환합니다.
OpenAI — /v1/chat/completions (및 이미지/영상 엔드포인트)
Anthropic — /v1/messages
Gemini — /v1beta/models/{model}:generateContent
상태 코드 매핑
오류의type / status는 HTTP 상태 코드에서 파생됩니다.
모델 파라미터 거부
모델이 요청의 특정 값을 받아들이지 않으면 엔드포인트는 해당 모델의 설명과 함께 HTTP400을
반환합니다. 추론 설정으로 인한 거부는 오류 코드 invalid_reasoning_effort로 반환되며, 메시지에
그 모델이 허용하는 값이 나열되므로 추측 없이 요청을 바로 고칠 수 있습니다. 각 모델이 지원하는
추론 effort와 기본값, 추론 비활성화 가능 여부는 GET /v1/models의
capability_metadata.reasoning에 공개되어 있습니다.
속도 제한은 429를, 시간 예산을 초과한 요청은 504를 반환합니다. 502는 재시도 후에도
플랫폼이 모델에서 사용할 수 있는 답변을 얻지 못했다는 의미이며, 파라미터에 대한 판정이
아닙니다. 따라서 파라미터를 바꾸기 전에 응답 본문을 먼저 확인하세요.
미디어 생성 오류와 재시도
이미지와 영상 생성에서는 구조화된error.code와 작업의 status
(클라이언트의 task.status)를 기준으로 표시할 메시지와 재시도 여부를 결정하세요.
명시적인 정책 오류 코드나 분명한 콘텐츠 정책 거부가 있을 때만 콘텐츠 수정을 권장하세요.
메시지에
safety가 언급되거나 HTTP 502가 반환되었다는 이유만으로 정책 위반이라고
판단하면 안 됩니다. 비동기 작업이 pending 또는 processing이면 동일한 task_id로
/v1/tasks/{task_id}를 계속 조회하고, 생성 요청을 중복 제출하지 마세요.