API / Webhooks & errors
Errors
API errors return a consistent JSON envelope. Use the code to decide what your application should do next.
Error response
402 · Payment required
{
"error": {
"type": "payment_required",
"code": "insufficient_balance",
"message": "Top up your API balance before creating this check.",
"required_cents": 20,
"balance_cents": 12
}
}
Common error codes
| HTTP | Code | What to do |
|---|---|---|
| 400 | invalid_request | Read the message and correct the request. |
| 400 | document_too_short / document_too_long | Input must contain 125–50,000 words. |
| 400 | unsupported_file_type / empty_document | Use a supported document with readable text. |
| 401 | invalid_key / revoked_key | Use an active API key from the dashboard. |
| 402 | insufficient_balance | Add funds to the API wallet. |
| 404 | not_found | Check the ID and owning account. |
| 409 | not_ready | Wait for the report and try again. |
| 413 | file_too_large | Use a direct upload for files larger than 4 MB. |
| 429 | too_many_checks | Wait for a running check to finish. |
| 429 | too_many_uploads | Create checks from your waiting uploads, or let them expire. |
| 5xx | check_failed / unavailable | Retry with backoff; keep the same idempotency key for a logical check. |
When you need help
Include the check ID, HTTP status, error code, and approximate request time when contacting support. Never include your API key or webhook signing secret.
Still have a question? We’re here to help.