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

Uniform error messages

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

Most errors use the error envelope above. Rate-limit responses also include top-level limit, remaining, and reset fields.

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests."
  },
  "limit": 1000,
  "remaining": 0,
  "reset": 1787836800
}

For HTTP 429 rate limits, wait for the Retry-After header. allowance_exhausted instead includes error.details.used, limit, and periodEndsAt.

Error codes

These error codes use API version 2:

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 5,000 characters	Correct the request
400	idempotency_key_required	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	feature_not_available	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 the status query and start a new order if necessary
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 the request and contact support if the problem persists

Document for each error: can the request be repeated? are characters calculated? what is in the protocol? what information does support need?

On this page

Handle errors without losing the request context.

Uniform error messages

Error codes

Start using Simple8 for free.