오류의 형태
오류는 이 형태의 JSON입니다. 절대 바뀌지 않는 code로 분기하세요. message는 사람을 위한 것이며 바뀔 수 있습니다. 400일 때 details에 잘못된 필드가 모두 나열됩니다.
json
{
"error": {
"code": "insufficient_scope",
"message": "Insufficient permissions. Missing scopes: REDLINES_GENERATE",
"requestId": "0d6f3c1e-8a9b-4f2d-b7e5-91c4a2d3e6f0"
}
}코드
코드 이름을 앵커로 쓰면 해당 코드로 바로 연결됩니다. 예: /docs/api/errors#rate_limited
- 400invalid_request
- 본문, 쿼리 또는 헤더가 잘못되었습니다. details에 문제가 있는 필드가 모두 나옵니다. 요청을 고치세요. 그대로 다시 보내면 또 실패합니다.
- 401api_key_expired
- 키가 만료되었습니다. 새 키를 만들거나 키를 재발급해 새 비밀값을 받으세요.
- 401api_key_revoked
- 키가 폐기되었습니다. 설정 › 개발자에서 새 키를 만드세요.
- 401invalid_api_key
- 일치하는 키가 없습니다. 키 전체를 복사했는지 확인하거나 설정 › 개발자에서 새 키를 만드세요.
- 402insufficient_credits
- 키 소유자의 AI 크레딧이 모두 소진되었습니다. Attorly에서 충전하거나 업그레이드한 뒤 다시 시도하세요.
- 402usage_limit_exceeded
- 키 소유자 또는 조직의 AI 사용 한도에 도달했습니다. 청구 기간이 바뀌면 초기화되며, 조직 관리자가 구성원의 한도를 올릴 수 있습니다.
- 403ai_consent_withdrawn
- 키 소유자 또는 문서 소유자가 AI 처리 동의를 철회했습니다. 개인정보 설정에서 다시 동의할 수 있습니다.
- 403forbidden
- 키로 리소스를 읽을 수는 있지만 변경할 수는 없거나, 해당 작업이 허용되지 않습니다. 소유자에게 편집 권한을 요청하세요.
- 403insufficient_scope
- 이 작업에 필요한 권한이 키에 없습니다. 메시지에 해당 권한이 나옵니다. 그 권한을 포함한 키를 만드세요.
- 403ip_not_allowed
- 키에 IP 허용 목록이 있으며, 요청이 목록 밖의 주소에서 왔습니다. 허용된 주소에서 호출하거나 설정 › 개발자에서 목록을 변경하세요.
- 403plan_required
- 키 소유자의 요금제에 API 접근이 포함되어 있지 않거나 소유자가 조직을 떠났습니다. API 접근에는 Pro 또는 Enterprise가 필요합니다.
- 404not_found
- 리소스가 없거나 이 키로는 볼 수 없습니다. ID와 키 소유자의 접근 권한을 확인하세요.
- 405method_not_allowed
- 이 경로는 해당 HTTP 메서드를 지원하지 않습니다. Allow 헤더에 지원하는 메서드가 나옵니다.
- 409conflict
- 요청이 리소스의 현재 상태와 충돌합니다(이미 수행된 작업 등). 리소스를 다시 읽고 판단하세요.
- 409idempotency_request_in_progress
- 같은 Idempotency-Key의 요청이 아직 처리 중입니다. Location 헤더를 조회하거나 Retry-After초 후에 다시 시도하세요.
- 413payload_too_large
- 본문이나 업로드한 파일이 너무 큽니다. 파일은 최대 10 MB입니다.
- 415unsupported_media_type
- 이 작업이 받지 않는 형식의 본문입니다. JSON을 보내거나, 업로드가 가능한 경우 multipart/form-data를 보내세요.
- 422idempotency_key_reused
- 이 Idempotency-Key는 다른 요청에 이미 사용되었습니다. 서로 다른 요청마다 새 키를 사용하세요.
- 422unprocessable
- 요청은 유효하지만 실행할 수 없습니다(준거법이 선택되지 않은 문서의 분석 등). 무엇이 빠졌는지 메시지에 나옵니다.
- 429concurrency_limit_exceeded
- 조직이 동시에 실행할 수 있는 장시간 AI 작업 수에 이미 도달했습니다. 작업 하나가 끝나거나 Retry-After의 초만큼 기다린 뒤 다시 시도하세요.
- 429rate_limited
- 이 키가 집계되는 창 중 하나에서 요청이 너무 많습니다. Retry-After의 초만큼 기다린 뒤 다시 시도하세요. 어느 창이 가득 찼는지는 RateLimit 헤더에서 확인할 수 있습니다.
- 500internal_error
- Attorly에서 문제가 발생했습니다. 같은 Idempotency-Key로 다시 시도하세요. 계속되면 requestId와 함께 지원팀에 문의하세요.
- 504timeout
- 작업이 제시간에 끝나지 않았습니다. 같은 Idempotency-Key로 다시 시도하거나 Prefer: respond-async를 보내고 작업을 조회하세요.