Error Codes
The Extralt API returns standard HTTP statuses and one stable JSON error envelope:
{
"error": {
"code": "invalid_request",
"message": "robot_id is required",
"request_id": "019..."
}
}error.code is machine-readable. error.message is safe to show to a user.
error.request_id matches the x-request-id response header and should be
included when contacting support.
Codes
| HTTP | error.code | Meaning |
|---|---|---|
400 | invalid_request | The request syntax, query parameters, path values, or domain input is invalid |
401 | unauthorized | The Bearer credential is missing or invalid |
402 | payment_required | The organization needs a subscription or credits |
403 | forbidden | The credential or organization cannot access this operation |
404 | not_found | The route or organization-scoped resource does not exist |
405 | method_not_allowed | The route does not support that HTTP method |
409 | conflict | The operation conflicts with resource state or an idempotency key was reused with another payload |
413 | payload_too_large | The request body exceeds the API size limit |
415 | unsupported_media_type | A JSON route did not receive application/json |
422 | unprocessable_entity | JSON was parsed but could not be decoded into the requested schema |
429 | rate_limit_exceeded | The request exceeded an operational rate limit |
500 | internal_error | An unexpected server error occurred; internal details are not exposed |
503 | upstream_unavailable | A required upstream service is temporarily unavailable |
504 | request_timeout | The request exceeded its server-side time budget |
A 401 also includes WWW-Authenticate. A 429 includes Retry-After when
the server can calculate the delay.
Handling errors
The SDKs raise one error type per status, carrying
the envelope's code, message, and request ID:
from extralt import APIStatusError, Extralt
client = Extralt()
try:
client.extract.runs.create(robot_id=robot_id, budget=100)
except APIStatusError as error:
print(f"{error.code}: {error.message} ({error.request_id})")Other HTTP clients read the same envelope from the body of any 4xx or 5xx
response.
Retry reads after bounded backoff when appropriate. Retry create or restart
operations only with the same payload and original Idempotency-Key; changing
the payload requires a new key. The SDKs follow these rules for their own
retries.