Error Codes

Synchronous errors use the error.message/type/param/code structure; asynchronous failures use an internal standard error structure that requires separate handling.

Synchronous error structure

{
  "error": {
    "message": "billing error",
    "type": "billing_error",
    "param": null,
    "code": "insufficient_credits"
  }
}

HTTP	type	Description
400	`invalid_request_error`	Invalid request parameters
401	`authentication_error`	Authentication failed; framework-supported
402	`billing_error`	Billing or balance issue
403	`permission_error`	No permission, security interception; common landing point for current AGW API Key failures
404	`not_found_error`	Resource does not exist
409	`conflict_error`	Resource conflict
429	`rate_limit_error`	Rate limit or concurrency limit exceeded
500/502/503/504	`internal / upstream / service / timeout`	System, downstream, or service unavailable or timeout

Common codes

code	Description
`missing_required_field`	Missing required field
`invalid_field_value`	Invalid field value
`unsupported_response_format`	Unsupported output format
`invalid_url` / `url_not_allowed`	Invalid URL format or access not allowed
`insufficient_credits`	Insufficient balance
`rate_limit_exceeded` / `concurrency_limit_exceeded`	Request frequency or concurrency limit exceeded
`file_not_found` / `voice_not_found` / `task_not_found`	Resource does not exist
`safety_guardrail_blocked`	Blocked by safety detection

Asynchronous failure structure

When an asynchronous task fails, status is FAILED and error is an internal standard error structure, which differs from the synchronous error structure.

{
  "id": "task-xxx",
  "object": "audio.speech",
  "status": "FAILED",
  "error": {
    "error_code": 16001,
    "error_msg": "billing error",
    "internal_error_code": 109111005,
    "internal_error_msg": "insufficient credits"
  }
}