Errors and Retries

JSON errors use a stable machine-readable envelope:

{
  "error": {
    "code": "order_book_version_stale",
    "message": "The supplied book version is no longer current.",
    "requestId": "req-...",
    "details": {}
  }
}

Branch on error.code, never on the human message. Include requestId when reporting a problem, but do not include developer keys, session tokens, webhook signatures or raw signed payloads in logs or support messages.

HTTP classification

Status	Meaning	Typical action
`400`	Invalid syntax, field, cursor or unsupported combination	Fix the request; do not retry unchanged
`401`	Missing, expired or invalid credential	Reauthenticate/rotate; never move the credential to a query string
`403`	Credential is valid but lacks scope or user ownership	Ask for the correct user authority or reduce the operation
`404`	Resource is not visible or does not exist	Stop or refresh discovery state
`409`	Stale version, lifecycle conflict or idempotency conflict	Reconcile current state before deciding whether to retry
`429`	Rate or connection limit	Honor `Retry-After` and add jitter
`500`	Unexpected Aura failure	Retry only an idempotent operation with backoff
`503`	Required sequencer, wallet, indexer, node or realtime source unavailable	Preserve state and retry with backoff

Security-sensitive conflicts

developer_scope_missing: the developer key does not have the required scope. A wallet session does not add that scope.
account_scope_mismatch / account_forbidden: the requested account is not the signed-in wallet.
idempotency_secret_unrecoverable: an earlier request created a one-time secret. Aura cannot show it again; rotate the key/webhook.
stale book/version errors: fetch a new book or quote and ask the user to accept changed execution terms.
private webhook authorization errors: the matching wallet must authorize or renew the endpoint; the builder key cannot do it alone.
funding_requirements_unavailable: Aura could not obtain a valid authenticated wallet-runtime confirmation policy. Freeze the deposit flow; never substitute a client-side confirmation default.

Realtime errors are frames

After an SSE connection is established, Aura can send event: aura-error with recoverable, code, requestId and lastCursor. It can also send event: aura-reset. A reset is not a normal retry: replace local state from a fresh snapshot and resume after that snapshot’s cursor. The stable stream codes are slow_consumer, replay_unavailable, session_expired, session_revoked, session_revalidation_unavailable, developer_key_revoked, developer_key_expired, developer_key_rotated, developer_key_scope_changed, developer_key_generation_changed, developer_key_revalidation_unavailable, and source_unavailable. Session and developer-key lifecycle failures require fresh authority before reconnecting; revalidation/source outages and replay failures use bounded backoff while local state remains frozen. See the realtime guide for the per-code recovery table. Malformed schema-v2 events, source-vector divergence and JSON numbers in event money fields are protocol errors. Stop applying them and resynchronize rather than guessing.

Safe retry rules

Reuse the same idempotency key only for the same logical write.
Do not retry a non-idempotent write merely because the response was lost; first query its status or reconcile its transaction/order identifier.
Batch cancellation can partially succeed. Process each result instead of retrying the entire batch with a new key.
Webhooks are at least once. Deduplicate the durable event ID and acknowledge duplicates successfully.
Once an Alephium transaction is broadcast, use GET /v1/transactions/{txId} rather than blindly submitting a replacement.

@aura/builder-sdk throws AuraApiError with status, code, requestId, details and rate-limit metadata.

Get Started

Guides

Reference

Endpoints

Realtime Stream

Errors and Retries

HTTP classification

Security-sensitive conflicts

Realtime errors are frames

Safe retry rules

​HTTP classification

​Security-sensitive conflicts

​Realtime errors are frames

​Safe retry rules

HTTP classification

Security-sensitive conflicts

Realtime errors are frames

Safe retry rules