Errors & response envelope

All responses use the same envelope; successes and errors just fill different fields. Errors carry a stable code you can switch on in your code, and every response includes a request_id for support tickets.

Success envelope

{
  "data": { ... },              // endpoint-specific payload
  "meta": {
    "request_id": "abc-123",    // matches the X-Request-Id header
    "cached_at": "2026-07-11T12:34:56Z"
  }
}

Field	Type	Description
`data`	object \| array	Endpoint-specific payload. Array for list endpoints, object otherwise.
`meta.request_id`	string	Mirrors `X-Request-Id`. Include when reporting an issue.
`meta.cached_at`	string (ISO 8601)	When the API rendered the response — not the source data freshness (typically 1-2s fresher for token snapshots).

Error envelope

{
  "error": {
    "code": "not_found",
    "message": "No token with mint 'BgN...' is currently tracked.",
    "request_id": "abc-123",
    "retry_after": 42           // only on rate_limited (seconds)
  }
}

retry_after only appears on rate_limited. Every other field is always present.

HTTP status → error code

Status	code	When
400	`bad_request`	Malformed URL parameter (e.g. non-base58 mint or wallet address).
401	`unauthorized`	Missing, malformed, or unknown API key.
403	`forbidden`	Key exists but is revoked.
404	`not_found`	Resource does not exist or has not been observed yet.
429	`rate_limited`	Per-key or per-IP limit exceeded. Honour `Retry-After`.
500	`internal_error`	Unexpected server-side failure. Report with `request_id`.

Client patterns

Retry on 429 using the Retry-After value; skip retry for bad_request or forbidden.
Log the request_id — makes issue reports 10× faster.
Dispatch on code, not message. Messages are human-readable and may improve; codes are stable.

Terms and Conditions

Errors & response envelope

Success envelope

Error envelope

HTTP status → error code

Client patterns