Error Codes
Centralized error response format and code semantics for API.
All errors return this shape:
{
"error": {
"message": "Human-readable message",
"type": "invalid_request_error",
"param": "input",
"code": "input_too_long"
}
}Error Types
invalid_request_error: Request shape or parameter invalid.authentication_error: Missing or invalid API key.permission_error: Account is authenticated but operation is blocked (for example, insufficient credits).not_found_error: Referenced resource does not exist.rate_limit_error: Request exceeds configured rate limits.server_error: Internal processing failure.
Common Codes
| Code | Type | Meaning |
|---|---|---|
invalid_request | invalid_request_error | Request body failed validation. |
unsupported_parameter | invalid_request_error | Parameter is not supported. |
unsupported_response_format | invalid_request_error | Requested format is unsupported for selected model. |
input_too_long | invalid_request_error | Input exceeds model limits. |
voice_not_found | not_found_error | Voice ID does not exist, or voice name does not exist for the requested model. |
invalid_api_key | authentication_error | Bearer key missing/invalid/inactive. |
insufficient_credits | permission_error | Account balance is too low. |
rate_limit_exceeded | rate_limit_error | Too many requests. |
provider_quota_exceeded | rate_limit_error | Provider quota or billing is temporarily exhausted. |
content_policy_violation | invalid_request_error | Content blocked by provider safety policy. |
provider_unavailable | server_error | Upstream provider is temporarily unavailable; retry later. |
server_error | server_error | Internal service or provider failure. Responses use HTTP 500 or 503; retry 503 responses with backoff. |
Voice lookup errors and client compatibility
POST /api/v1/speech returns HTTP 404 with error.code = "voice_not_found"
when a voice ID is unavailable or a voice name does not exist for the requested
model. This applies to every supported model, including gpro, gpro31,
orpheus, and xai, as well as gpro38.
If your client handles HTTP 400 with model_not_found, also handle HTTP 404
with voice_not_found for voice/model mismatches. Select an available voice ID
or a matching name and model from GET /api/v1/voices before retrying. Invalid
request shapes and unsupported model values still return HTTP 400 validation
errors.
Debugging with request-id
Every response includes request-id header. Save it with your logs and include it in bug reports.