Errors, Retries and Idempotency
The RIXL API error format, what each status means, when to retry, and how to make retries safe.
Use this page to diagnose the most common RIXL API failures and choose the correct recovery strategy.
Error Format
Every error response has a JSON body with one field:
{"error": "invalid request"}The message is for humans and is not stable. Branch on the HTTP status code.
Status Codes
| Status | Meaning | Retry? |
|---|---|---|
400 | Invalid request, failed precondition, or invalid Idempotency-Key | No |
401 | Missing, invalid, revoked or expired credential | No |
403 | The credential is valid but may not access this resource | No |
404 | The resource or route does not exist | No |
409 | Conflict. With Retry-After: an idempotent request with the same key is still in flight | Only when Retry-After is present |
429 | Too many requests (see Rate Limits) | Only when Retry-After is present |
500 | Internal error | No |
501 | Not implemented | No |
502 | Unexpected upstream failure, or an edge proxy could not reach the API | Yes, for idempotent requests |
503 | A backend is unavailable, overloaded, or reset the request | Yes, for idempotent requests |
504 | A backend did not answer in time | Yes, for idempotent requests |
Retry-After is sent on 503 and most 504 responses, and on 409 and 429 only when a retry can succeed. When a retryable response has none, use the backoff below.
Retries
Retry a request only if both hold:
- The request is idempotent:
GET,HEAD,PUTorDELETE, or aPOSTthat carries anIdempotency-Key. - The failure is transient: a network error or timeout,
502,503,504, or a409or429that has aRetry-Afterheader.
Never retry 400, 401, 403, 404, 500 or 501, or a 409 or 429 without Retry-After. Fix the request; a 429 without Retry-After is a long cooldown (for example on repeated verification emails), not a transient limit.
Delay:
- If the response has
Retry-After, wait that many seconds. - Otherwise use exponential backoff with full jitter: wait a random time between 0 and
min(8s, 0.5s × 2^attempt). - Stop after 3 retries and surface the last response.
const RETRYABLE = new Set([502, 503, 504]);
const IDEMPOTENT = new Set(["GET", "HEAD", "PUT", "DELETE"]);
async function fetchWithRetry(input: string, init: RequestInit = {}): Promise<Response> {
const method = (init.method ?? "GET").toUpperCase();
const canRetry = IDEMPOTENT.has(method) || new Headers(init.headers).has("Idempotency-Key");
for (let attempt = 0; ; attempt++) {
let response: Response | undefined;
try {
response = await fetch(input, init);
} catch (err) {
if (!canRetry || attempt === 3) throw err;
}
const retryAfter = response?.headers.get("Retry-After");
const transient =
!response || RETRYABLE.has(response.status) || ((response.status === 409 || response.status === 429) && retryAfter !== null);
if (response && (!canRetry || !transient || attempt === 3)) return response;
const delay = retryAfter ? Number(retryAfter) * 1000 : Math.random() * Math.min(8000, 500 * 2 ** attempt);
await new Promise((resolve) => setTimeout(resolve, delay));
}
}For more throttling guidance, see Rate Limits.
Retrying a POST without an Idempotency-Key can create the resource twice, for example a second upload. Send a key, or don't retry.
Idempotency
Send an Idempotency-Key header to make a POST safe to retry. It is currently honoured on:
CreateVideoUpload(POST /media/v1/projects/{project_id}/videos/upload)
On other operations the header is ignored, so a POST there is still not safe to retry.
| Situation | Response |
|---|---|
No Idempotency-Key header | Behaves as today (the header is optional) |
| Key not 1–255 visible ASCII chars | 400 "invalid Idempotency-Key" |
| First request with the key | Runs normally; a successful response is stored for 24h |
| Same key, same request, completed | The stored response is replayed (same IDs, URLs, expires_at), with header Idempotent-Replayed: true |
| Same key, different request body or path | 400 "Idempotency-Key was reused with a different request" |
| Same key while the first request is in flight | 409 "a request with this Idempotency-Key is in progress", Retry-After: 1 |
| First request failed | Nothing is stored, so the client may retry with the same key |
- Use a fresh random value, such as a UUID, for each logical operation, and reuse it only to retry that operation.
- Keys are scoped to your organisation, so they never collide with another customer's. Within an organisation, a user's keys are their own, while all API keys of one project share a single namespace: two services using different API keys on the same project must not reuse each other's
Idempotency-Keyvalues. - The in-flight lock lasts 60 seconds. If the first request has not finished by then, a retry with the same key runs the operation again.
- A replay returns the stored response as-is, even after its presigned URLs have expired. Check
expires_atand start a new upload with a new key if they have. - Only the in-flight
409carriesRetry-After. Any other409is a real conflict; don't retry it. - Replayed responses still count as billed API requests.
Request IDs
Send an X-Request-Id header (1–128 visible ASCII characters) with each request. The API echoes it on the response; if you send none, or an invalid one, it generates one. Log it, and quote it when you contact support.
Lost API Key
API keys are shown once at creation. If the value is lost, revoke the key and create a new one.