Errors

The envelope

Errors are returned as JSON with a stable shape: a machine-readable code, a human-readable message, and the request identifier. The request identifier is the field to log.

Status codes and what they mean

Status	Meaning	Retry
400	The request was malformed or a value was invalid	No, fix the request
401	Missing or invalid credentials	No
403	Authenticated but not permitted	No
404	Route not found, or the asset is not in the active generation	Depends. Check readiness first
405	Method not allowed on a known route	No
409	A conflict, such as an idempotency mismatch	No, inspect the conflict
414	The request URL is too long	No
429	Rate limited, where a limit is implemented	Yes, with backoff
500	An unexpected server error	Yes, with backoff
503	Not ready, unavailable, or degraded	Yes, after checking readiness

The 404 that is not an error

A 404 on an asset route can mean the asset does not exist, or that it is not in the active generation, or that it is outside this projection. Those are different.

Check /ready and the projection before concluding anything is missing. See unavailable index against empty balance.

Named codes you will see

Code	Meaning
NFT_NOT_FOUND	No plain NFT with that Atomical ID in the active generation
REALM_NOT_FOUND	No Realm or Subrealm with that Atomical ID in the active generation
ASSET_NOT_FOUND	No asset of any projected type with that Atomical ID
NFT_MEDIA_NOT_FOUND	The asset exists, the requested media field does not
METHOD_NOT_ALLOWED	Known route, wrong method. The allow header names the right one
METRICS_DISABLED	Metrics are turned off on this deployment
NOT_FOUND	The route itself does not exist

Validation errors

Validation failures carry a specific reason rather than a generic message. A malformed Atomical ID, an out-of-range page, an unsupported kind filter, and a malformed media field name each report what was wrong.

Unicode and IDNA name errors are surfaced explicitly rather than being flattened into a generic validation failure.

What a client should do

1. Log the request identifier with every failure.
2. Distinguish client mistakes from service states before retrying.
3. Retry only 429, 500, and 503, with exponential backoff and jitter.
4. On 503, read /ready and use its reason rather than retrying blindly.
5. Never treat 404 as “the asset was destroyed”.

Source

Readiness and freshness and NFT and Realm API.