Errors & retries

Every error from beatra has the same shape and tells you whether it's safe to retry. Follow the one flag.

Error shape

{
  "error": {
    "code": "rate_limited",
    "message": "Request budget exhausted; retry later.",
    "retryable": true,
    "request_id": "req_01J5..."
  }
}

The full list of code values lives in Error codes.

The one rule

• Retry only when retryable is true.
• Use exponential backoff with jitter.
• Reuse the same Idempotency-Key on every retry of the same logical operation.
• Stop after a reasonable number of attempts and show a stable message to your user.

What never to retry

Validation errors, authentication errors, and permission errors are deterministic. Retrying them gives the same answer and burns quota. Surface a clear message and let the user correct the input or contact support.

Logging

• Store the request_id from every error alongside the user-facing job record.
• Keep the response X-Request-Id header even when the call succeeds — it's the same id and the fastest way to find a request in support.

Customer-facing messages

Don't show raw code or message values to end users. Map a small set of intents (busy, invalid input, please retry, contact us) and translate the technical error into your own copy.