Errors
Errors are RFC 9457 problem documents, and you should branch on
code. The status appears in the body as well as on
the response. Every error carries a request_id, which is also
sent as the X-Request-Id header, and a retryable
boolean that says whether sending the same request again can succeed. A
429 or 503 response also carries
Retry-After in whole seconds. Successful responses carry
X-Request-Id too, in the header only.
Two statuses mean that the work has already run. A 504 with
code timeout means the service stopped waiting while the
prediction continued to the end, and it is counted in full. A 502
with code upstream_unavailable means the prediction ran but its
answer could not be read. Both carry retryable: false, because a
second attempt would be counted again, so send a smaller table instead. The
Python client never retries either of them, whatever the body says.
The type of every error links to its row in the table below.
The Python client raises one exception class for each group of codes, and the
Usage, limits and
cancellation example lists which class covers which codes.
| code | status | What happened | What to do |
|---|---|---|---|
unauthorized | 401 | No key, a wrong key, or one that has been revoked. | Check the key. A revoked key stops working within about a minute, or within 15 minutes while our key store is unreachable. |
validation_failed | 422 | The tables or the params do not fit the contract. | The detail names the column or field. Feature columns must match in name and order. |
bad_request | 400 | The body could not be parsed at all. Only a container you run yourself answers this way; the hosted API reports the same request as validation_failed. | Check the content type and that both parts are present. |
empty_body | 400 | The request arrived with no body. | Send the tables. A proxy that strips bodies will produce this. |
payload_too_large | 413 | The body is over this deployment's ceiling. | Send fewer rows, or store the context once and name it afterwards. |
request_too_large | 413 | The table is over the row or cell cap, or would take longer than the deployment allows. | The detail says how many context rows fit at your column count. |
context_not_found | 404 | The stored context has expired or been released. | Send the table again. The Python client does this for you. |
quota_exceeded | 429 | The monthly or daily cell cap. | The body says which cap, what is used and when it resets. |
rate_limited | 429 | Too many requests in the minute or hour window. The cell caps are separate. | Wait for the Retry-After seconds and resend. |
response_too_large | 413 | The prediction is bigger than can be returned. | Ask for fewer query rows. Nothing counts against your allowance. |
not_ready | 503 | The service is starting or being replaced. | Retry. This is not an error on your side. |
unavailable | 503 | The GPU was busy for the whole wait, the service is short of memory, or it is shutting down. | Retry. Nothing counts against your allowance. |
upstream_unavailable | 502 or 503 | 502: the prediction ran and its answer could not be read; its cells count. 503: a store the service depends on could not be reached before the work started. | On a 502, do not resend; send a smaller table. On a 503, retry. retryable says which. |
inference_failed | 500 | The prediction failed inside the service. | Nothing counts against your allowance. Quote the request_id if it repeats. |
client_gone | 499 | The caller disconnected before the answer was returned. | Recorded in the logs only. You will not receive this one. |
cancel_key_in_use | 409 | Two requests sent the same cancel key. | Use a fresh key per request. |
not_found | 404 | No such route. | Check the path. |
method_not_allowed | 405 | Wrong method for that route. | Check the method. |
not_implemented | 501 | The route exists but this deployment cannot do it. | POST /v1/cancel is the only one. A call that has started cannot be stopped. |
timeout | 504 | The service did not answer within its own wait. | The work is still running and is counted. Do not retry; send a smaller table. |