Errors

Error response shape

Every error response shares a common JSON shape:

1
{
2
  "code": "rate_limit_exceeded",
3
  "message": "Too many requests.",
4
  "docs_url": "https://docs.agora.finance/api/errors"
5
}

Every response — success or error — also includes a Request-Id header. Log it; Agora support uses it to trace requests end-to-end.

Error codes

Authentication failures (401)

A 401 unauthorized response carries a context.reason naming the specific cause, so clients can branch without parsing message:

1
{
2
  "code": "unauthorized",
3
  "message": "Authentication is required.",
4
  "docs_url": "https://docs.agora.finance/api/errors",
5
  "context": { "reason": "token_expired" }
6
}

See the Authentication guide for the full exchange and refresh flow.

Error context

Three codes attach a context object; all others omit it.

parameter_invalid returns a context.issues array describing each validation failure:

1
{
2
  "code": "parameter_invalid",
3
  "message": "One or more request parameters are invalid.",
4
  "docs_url": "https://docs.agora.finance/api/errors",
5
  "context": {
6
    "issues": [
7
      { "field": "amount", "message": "Must be a positive decimal string." },
8
      { "field": "destination.chain", "message": "Unsupported chain. Supported: ethereum, solana, monad." }
9
    ]
10
  }
11
}

unauthorized returns a context.reason — see Authentication failures above.

route_already_exists returns a context.routeId — the id of the pre-existing route. Route ids are deterministic, so you can use it directly (e.g. fetch the route via GET /v0/routes/{routeId}).

Handling errors programmatically

• Match on code, never on message. Messages are human-readable and may change without notice. For 401, branch on context.reason.
• Use the HTTP status as a secondary filter. Status plus code together fully disambiguate every error.
• Persist the Request-Id header. It is the single best lever for diagnosing issues with Agora support.
• Retry-with-backoff for 429, 500, and 503. Honor Retry-After when present. The 503 codes (route_creation_unavailable, service_unavailable) are transient and safe to retry.