Agora Public API

Errors

HTTP status codes, error codes, and recommended handling.

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}
FieldTypeDescription
codestringMachine-readable error code. Stable — safe to match on in code.
messagestringHuman-readable explanation. May change without notice — do not match on it.
docs_urlstringLink back to this page for deeper context.
contextobject | omittedPer-error structured details. Present only when the error type uses them — see Error context below.

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

HTTPcodeWhen it happensRecommended handling
400parameter_invalidOne or more request parameters fail validation, including malformed paths or unsupported methods. The response includes a context.issues array with per-field details.Inspect context.issues for the offending field and message; correct the request and retry.
401unauthorizedAuthentication is required for the requested resource.Provide an API key and retry.
403forbiddenAuthentication succeeded but the credential does not have permission to access this resource.Confirm the key is provisioned for the requested resource; otherwise contact your Agora account manager.
404not_foundThe requested route or resource does not exist.Verify the URL and method. The current public surface is documented under Endpoints.
429rate_limit_exceededThe caller has exceeded the per-IP rate limit at the Cloudflare edge. The response includes a Retry-After header indicating the wait period in seconds.Wait the duration given in Retry-After, then retry. Implement exponential backoff for repeat triggers.
500internal_errorAn unexpected server-side failure. The response intentionally omits internal details.Retry with exponential backoff. If the error persists, capture the Request-Id header and contact support.

Error context

When the API returns a 400 status and the parameter_invalid code, the body will include 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}

Illustrative example. The fields shown above are illustrative — current endpoints take no parameters. The context.issues shape is stable across every endpoint that emits parameter_invalid.

Handling errors programmatically

  • Match on code, never on message. Messages are human-readable and may change without notice.
  • 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 and 5xx. Honor Retry-After when present.