API REFERENCE · PREVIEW

Errors & rate limits

A consistent error envelope and predictable retry behavior.

Error envelope

Non-2xx responses use a structured error. Branch on error.code; the message is for diagnostics and can change. Include requestId when escalating a problem.

JSON — 422 EXAMPLE

{
  "error": {
    "code": "invalid_transaction",
    "message": "signedTransaction must be a signed, 0x-prefixed EVM transaction.",
    "field": "signedTransaction"
  },
  "requestId": "req_example_003"
}

HTTP status & error codes

HTTP	Code	Action
400	`invalid_request`	Correct JSON, required fields or headers.
401	`unauthorized`	Supply a valid API key.
403	`network_not_enabled`	Check network access with the team.
404	`transaction_not_found`	Check ID and integration scope.
409	`idempotency_conflict`	Use the original body or a new key for a genuinely new submission.
422	`invalid_transaction`	Correct the signed transaction or network mismatch.
429	`rate_limited`	Wait for Retry-After, then back off.
500	`internal_error`	Retry with backoff; preserve the submission key and body.
503	`temporarily_unavailable`	Respect Retry-After when present; use bounded retries.

Proposed limits

The preview contract uses a shared budget of 120 requests per minute per API key, across submission and status queries. This is a design value, not a production capacity commitment.

ILLUSTRATIVE RESPONSE HEADERS

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 10
X-Request-ID: req_example_004

Retry strategy

Do not automatically retry validation, authentication or scope errors.
For 429 and transient server errors, apply exponential backoff with jitter and a maximum elapsed time.
Reuse the exact idempotency key and request body after an uncertain submission.
Keep polling within the same budget; increasing polling frequency cannot make a transaction land sooner.
Review the privacy implications before using a public fallback route.

Escalation evidence

Capture the network, UTC timestamp, request ID, submission ID if known and redacted error. The support brief provides a template.

Updated September 20, 2026 · Discuss this guide ↗