Skip to main content
database_unavailable means the service could not reach its data store, or read a record from it, while handling your request. Read this page when any route answers with this code.

What happened

Routes: the runs routes (/v1/runs*), the keys routes (/v1/keys*), the usage routes (/v1/usage* and /v1/quota), and the billing routes (/v1/billing*). The data store failed while serving the request: the connection failed, or a stored record could not be read. Nothing in your request causes this. On POST /v1/runs the data store is used before the run is admitted and again while it runs, so the run may or may not have been stored.

How to fix

  • Retry with backoff (for example 2, 4, 8 and 16 seconds). Log the request_id of every failed attempt.
  • POST /v1/runs: retry with the same Idempotency-Key first. If the run was stored and finished, you get it back with "replayed": true and are not charged twice. If you get 202 with "state": "pending", the run was stored but never ran; retry again with a new key.
  • POST /v1/keys and POST /v1/keys/{key_id}/rotate: list keys with GET /v1/keys before you retry, so you do not create or rotate twice.
  • POST /v1/billing/checkout: retrying is safe; you only pay on the checkout page it returns.
  • If it persists for several minutes, report a request_id.

Example

Retrying a read with backoff and your own request id:
  • Error handling - a status-to-action table and a retry helper for every error.
  • Idempotency - when to reuse an Idempotency-Key and when to send a new one.
  • Request ids - send your own x-request-id and quote it when you report a problem.
  • Problem codes - every code, its status, and whether a retry can help.