Errors

Sandbox errors use the same codes and shapes as production. A few behave differently:

• Dashboard fixes. The sandbox has no dashboard yet. Where a fix below says to use the dashboard, contact Agora instead.
• direction_unsupported is returned for any route pair outside the four the sandbox supports.
• route_creation_unavailable means the sandbox ran out of deposit addresses. It refills, so retry shortly.

Error response shape

Every error response shares a common JSON shape:

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

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:

{
  "code": "unauthorized",
  "message": "Authentication is required.",
  "docs_url": "https://docs.agora.finance/api/errors",
  "context": { "reason": "token_expired" }
}

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:

{
  "code": "parameter_invalid",
  "message": "One or more request parameters are invalid.",
  "docs_url": "https://docs.agora.finance/api/errors",
  "context": {
    "issues": [
      { "field": "amount", "message": "Must be a positive decimal string." },
      { "field": "destination.chain", "message": "Unsupported chain. Supported: avalanche-fuji, ethereum-sepolia." }
    ]
  }
}

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.