Every response, successful or not, uses the same envelope. A failed call has data: null and one or more entries in errors:
{
"data": null,
"errors": [
{
"code": "conversion_failed",
"message": "Requested conversion is not supported",
"field": null
}
],
"meta": {
"request_id": "req_2f8c1d4a9b3e",
"timestamp": "2026-10-27T09:41:07.512Z",
"version": "2026-03-26"
}
}
code is the part to branch on: it is stable and machine-readable. message is written for people and may change. field is filled only for validation errors and names the body path that failed, for example body -> content.
| Status | Meaning | What to do |
|---|---|---|
400 |
The body matches the operation schema but the operation rejected it. code names the reason, for example conversion_failed or invalid_base64. |
Fix the input. Retrying the same call cannot succeed. |
413 |
The request is larger than the API accepts, 100 MB today, or it arrived without a Content-Length header (chunked bodies are refused). |
Send a smaller body with a Content-Length header. |
422 |
The body does not match the operation schema. One entry per problem, each with the code validation_error and the failing field. |
Read every entry and fix the fields listed. |
500 |
Something failed on the server. The envelope is the same and errors may be empty. |
Retry later, and quote the request_id when you ask for help. |
501 |
The operation is planned and not live yet. Nothing was executed. | Do not call it. Watch the changelog. |
A request to a path or method that does not exist still answers the envelope, with the code not_found or method_not_allowed.
Keep the request_id
Every failure carries a request_id in meta. It links the call to the server logs, so include it whenever you report a problem.
Bodies are JSON sent with Content-Type: application/json. A body that is not valid JSON answers 422 with the code validation_error.