Getting started

Errors

Error format, status codes and when to retry.

Errors use regular HTTP status codes and always return the same JSON envelope with a stable machine-readable code.

Error format#

{
  "error": {
    "code": "rateLimited",
    "message": "Rate limit exceeded",
    "retryAfter": 12
  }
}

error.code is stable and safe to branch on. error.message is a human-readable hint that may change. Some errors add fields: retryAfter for rate limits, reason for quotas and plan gates, issues for validation errors.

Error codes#

Status	Code	Meaning	Retry?
400	validation	A parameter or the body is invalid; see `error.issues`.	No
401	unauthorized	The API key is missing, malformed or revoked.	No
402	planRequired	Your plan doesn't include API access or this feature.	No
403	forbidden	The request isn't allowed.	No
404	notFound	The token wasn't scanned or the wallet wasn't profiled yet.	Later
409	conflict	The request conflicts with the current state.	No
429	rateLimited	Too many requests per minute, or the monthly quota is used up.	Yes
500	generic	Something failed on our side.	Yes
503	unavailable	Maintenance or the data provider is out of capacity.	Later

Validation errors#

Invalid parameters return 400 with a list of issues that point to the offending field.

400

{
  "error": {
    "code": "validation",
    "message": "Invalid input",
    "issues": [
      {
        "path": "pageSize",
        "message": "Invalid input"
      }
    ]
  }
}