to/human
to/human

Errors

The ToHuman API uses conventional HTTP response codes to indicate the success or failure of a request. Codes in the 2xx range indicate success, codes in the 4xx range indicate a client error, and codes in the 5xx range indicate a server error.

Error codes

Status Description
200 Request succeeded.
201 Resource created successfully.
401 Unauthorized — missing or invalid API token.
403 Forbidden — your token doesn't have permission for this action.
402 Payment required — your monthly word allowance is used up. Upgrade to Pro or buy a word pack to continue.
404 Not found — the requested resource doesn't exist.
422 Unprocessable content — the request body is invalid or missing required fields.
429 Too many requests — you've exceeded the rate limit.
500 Internal server error — something went wrong on our end.

Error response format

When an error occurs, the API returns a JSON response with an error field describing the issue:

422 Unprocessable Content 
{
  "error": "Content is required"
}
401 Unauthorized 
(empty body — check the status code)

When your account's monthly word allowance (2,500 words on Free, 100,000 on Pro) and any purchased word credits are used up, humanization requests return 402 Payment Required with your usage numbers and the ways to continue. Nothing is created or charged for a rejected request, and the very next request succeeds as soon as you upgrade or top up:

402 Payment Required 
{
  "error": "Monthly word allowance reached.",
  "words_used": 2534,
  "word_cap": 2500,
  "word_credits": 0,
  "upgrade_url": "https://tohuman.io/pricing",
  "word_pack_url": "https://tohuman.io/checkout?plan=pack"
}

Requests that exceed the sync word limit return a message pointing you to the async endpoint:

422 Validation error 
{
  "error": "Content exceeds 2000 word limit for sync. Use async endpoint instead."
}