Basics
Errors
What each status code means, what the body looks like and what to do.
Rowland uses standard HTTP status codes, and every error has the same body:
{
"error": {
"type": "invalid_request",
"code": "file_too_large",
"message": "Files can be up to 50 MB.",
"param": "file"
}
}type: the kind of error (below).code: a stable value to branch on.message: a sentence for your logs. It may change; do not match on it.param: the parameter at fault, when there is one.
Types
| Status | type |
Common codes |
What to do |
|---|---|---|---|
400 |
invalid_request |
missing_parameter, invalid_parameter, file_too_large, unsupported_file, empty_file |
Fix the request. |
401 |
authentication |
missing_api_key, invalid_api_key, expired_api_key |
Send a valid key in x-api-key. |
402 |
billing |
insufficient_credits, plan_required |
Top up or upgrade, then retry. |
403 |
permission |
not_allowed |
Use a key with the right scope. |
404 |
not_found |
not_found |
Check the ID, and which key you are using. |
409 |
conflict |
still_processing |
Wait until the object is ready. |
429 |
rate_limit |
too_many_requests |
Slow down and retry after Retry-After seconds. |
5xx |
server |
internal_error |
Retry with backoff. If it persists, contact support. |
Retrying safely
- Retry
429,5xxand network errors with exponential backoff, such as 1, 2, 4 and 8 seconds. - Do not retry other
4xxerrors unchanged: they fail the same way. - Uploading the same file twice is safe: Rowland recognizes it and returns the document you already have.
