Errors
ReWords.AI API error format, HTTP status codes and error codes, and which errors are charged.
Errors share one shape:
{ "error": { "code": "queue_full", "message": "30 jobs are already waiting. Retry in 30 seconds.", "details": {} } }| HTTP | Code | Charged | What to do |
|---|---|---|---|
| 400 | invalid_request | No | Fix the request body. Send exactly one image input, as application/json or multipart/form-data. |
| 400 | invalid_image | No | Send a JPEG, PNG or WebP up to 20 MB and 8000 px (JSON body up to 28 MB), or check that image_url can be downloaded. See Images. |
| 401 | invalid_api_key | No | Check the Authorization header. |
| 402 | insufficient_balance | No | Buy an edit pack. |
| 402 | insufficient_ocr_balance | No | Buy an OCR pack, or send text without box to POST /edits (OCR there is free). |
| 403 | image_blocked | No | The image failed content review. |
| 404 | not_found | No | The edit id does not exist for your account, or the path is wrong. |
| 422 | text_not_found | No | Retry with boxes from error.details.texts. |
| 429 | rate_limited | No | Wait Retry-After seconds. Limits: 30 submissions and 240 reads a minute. |
| 503 | queue_full | No | Wait Retry-After seconds. |
| 500 | upstream_failed | No | Something failed on our side. Retry after a few seconds. |
A request is checked in this order, and the first problem found is returned: API key (401), rate limit (429),
request body (400 invalid_request), image (400 invalid_image), balance (402), content review (403), queue
(503), text matching (422). So an account with no balance that sends a broken body gets 400, not 402.
Timeouts, network errors and 5xx
If POST /edits times out, the connection drops, or you get a 5xx, you cannot tell whether a job was created.
Retry with the same Idempotency-Key: if the first request did create a job, you get that job back and are not charged
twice. POST /ocr needs no key — the same image within 24 hours is not charged again. Responses other than 2xx may
come from a proxy and not be JSON, so check the status before parsing the body.
The errors above are returned when you make the request. Jobs that fail later, while processing, report
content_blocked, ai_generation_failed, timeout, upstream_failed or invalid_image in the job's error.code,
and are not charged. See Results and refunds.
Getting help
An error you cannot explain, a job that stays queued past 60 minutes, or a result that is wrong: write to
[email protected] with the job id, the time in UTC and the
error you got, or reach us on WhatsApp or TikTok from the contact page. The
FAQ lists what to include.
Webhooks
Receive a signed ReWords.AI webhook when an edit finishes, and verify the X-Rewords-Signature HMAC in Node.js or Python.
FAQ
Answers to common questions about the ReWords.AI API — what OCR can read, fonts and longer text, removing text, A versus B, retries, billing, front-end use, SDKs and how to get help.