Documentation

Handle errors without losing the request context.

{
  "text": "Complex source content in the selected language.",
  "locale": "en",
  "mode": "simple-language"
}

SDK and cURL examples available

Error envelope

The Version 2 production error envelope contains an error object with stable code and message fields.

{
  "error": {
    "code": "invalid_request",
    "message": "Check the request fields."
  }
}

The optional details object carries machine-readable context such as retryAfterSeconds.

HTTP response headers carry authentication and retry metadata where applicable.

Required error catalog

The following codes are the current Version 2 contract.

HTTP	Code	Meaning	Client action
400	invalid_json	The request body is not valid JSON	Correct the JSON body
400	invalid_request	A field is missing, unknown, or invalid, or text exceeds 10,000 characters	Correct the request
400	invalid_idempotency_key	A job or batch request has no valid Idempotency-Key	Send a unique key of at most 255 characters
400	invalid_webhook_endpoint	The selected webhook endpoint is missing or inactive	Choose an active endpoint or use polling
401	invalid_api_key	The Bearer token is missing, invalid, or revoked	Check or replace the API key
402	billing_required	Billing must be updated before processing can continue	Update billing in the application
403	subscription_required	The workspace has no active entitlement	Choose a plan or contact support
403	email_not_verified	No owner or administrator email is verified	Verify an eligible account email
404	job_not_found	The job does not exist, belongs to another workspace, or has expired	Stop polling and create a new job if needed
404	batch_not_found	The batch does not exist, belongs to another workspace, or has expired	Stop polling and create a new batch if needed
429	rate_limited	The request rate has been reached	Respect Retry-After
429	concurrency_limit	Too many requests are processing at the same time	Retry after an active request finishes
429	allowance_exhausted	The monthly character limit is reached and additional usage is unavailable or disabled	Wait for the next billing period or enable additional usage on an eligible plan
502	processing_failed	The service could not process the text	Retry safely and contact support with the request ID if it continues

For every error, document retryability, billing effect, log visibility, and support information.

On this page