Skip to main content
Developer API errors come from the gateway, service auth layer, or backend handler. The REST status is mapped from the underlying gRPC status.

​
Common HTTP statuses

StatusMeaningCommon cause
400Bad requestMissing field, invalid enum, malformed public key, invalid transaction payload
401UnauthorizedMissing or invalid API key or developer credential
403ForbiddenAuthenticated caller cannot access the organization or resource
404Not foundResource id does not exist or is not visible to the caller
409ConflictResource already exists or current state does not allow the requested mutation
429Rate limitedAPI key or organization exceeded request limits
500Internal errorBackend handler or upstream service failed
503UnavailableDependency or backend service is unavailable

​
Error body

The gateway may return a gRPC-transcoded error body. The exact body can vary by service and gateway layer, so clients should key primarily on HTTP status and then log any returned code, message, or details. 
{
  "code": 3,
  "message": "invalid request",
  "details": []
}
Some legacy endpoints or SDK proxy routes may return an object-shaped error: 
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request parameters"
  }
}

​
Client handling

  • Retry 429 and transient 5xx responses with exponential backoff.
  • Do not retry validation failures without changing the request.
  • Treat 401 as an API-key or credential configuration failure.
  • Treat 403 as an organization/resource access failure.
  • Log request ids and non-sensitive identifiers, but do not log API keys, signed transactions, launch URLs, OTP values, or upstream provider payloads.