Error Codes - Extralt API

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

response = requests.post(
    "https://api.extralt.com/v1/extract/runs",
    headers={**HEADERS, "Idempotency-Key": "run-create-019..."},
    json={"robot_id": robot_id, "start_urls": [url]},
)

if response.status_code >= 400:
    error = response.json()["error"]
    print(f"{error['code']}: {error['message']} ({error['request_id']})")

const response = await fetch("https://api.extralt.com/v1/extract/runs", {
  method: "POST",
  headers: {
    ...headers,
    "Content-Type": "application/json",
    "Idempotency-Key": "run-create-019...",
  },
  body: JSON.stringify({ robot_id: robotId, start_urls: [url] }),
});

if (!response.ok) {
  const { error } = await response.json();
  console.error(`${error.code}: ${error.message} (${error.request_id})`);
}

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.