Skip to Content

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

StatusMeaningRetry?
400Invalid request, failed precondition, or invalid Idempotency-KeyNo
401Missing, invalid, revoked or expired credentialNo
403The credential is valid but may not access this resourceNo
404The resource or route does not existNo
409Conflict. With Retry-After: an idempotent request with the same key is still in flightOnly when Retry-After is present
429Too many requests (see Rate Limits)Only when Retry-After is present
500Internal errorNo
501Not implementedNo
502Unexpected upstream failure, or an edge proxy could not reach the APIYes, for idempotent requests
503A backend is unavailable, overloaded, or reset the requestYes, for idempotent requests
504A backend did not answer in timeYes, 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:

  1. The request is idempotent: GET, HEAD, PUT or DELETE, or a POST that carries an Idempotency-Key.
  2. The failure is transient: a network error or timeout, 502, 503, 504, or a 409 or 429 that has a Retry-After header.

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.

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.

SituationResponse
No Idempotency-Key headerBehaves as today (the header is optional)
Key not 1–255 visible ASCII chars400 "invalid Idempotency-Key"
First request with the keyRuns normally; a successful response is stored for 24h
Same key, same request, completedThe stored response is replayed (same IDs, URLs, expires_at), with header Idempotent-Replayed: true
Same key, different request body or path400 "Idempotency-Key was reused with a different request"
Same key while the first request is in flight409 "a request with this Idempotency-Key is in progress", Retry-After: 1
First request failedNothing 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-Key values.
  • 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_at and start a new upload with a new key if they have.
  • Only the in-flight 409 carries Retry-After. Any other 409 is 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