Error Handling

The Heron API uses standard HTTP response codes to indicate the success or failure of an API request. In general:

• Codes in the 2xx range indicate success.
• Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.).
• Codes in the 5xx range indicate a server-side or upstream failure.

Error Response Body

When an error occurs, the API returns the error payload directly:

{
  "code": "invalid_request",
  "message": "The provided parameter 'amount' must be a positive number.",
  "details": {
    "field": "amount"
  }
}

details is optional. When present, it contains endpoint-specific context that can help you correct the request or understand why the operation could not be completed.

Error Codes

Heron uses resource-specific error codes rather than a tiny generic set. The route-level API reference is the source of truth for which codes each endpoint can return. Common public API codes include:

Code	Typical meaning
missing_credentials	No API credentials were provided.
unauthorized	The provided API key or bearer token was not accepted.
auth_failure	Heron's authentication infrastructure is temporarily unavailable.
invalid_request	The request shape or values were invalid. Check details when present.
insufficient_role	The credential is valid but does not carry the required role for the operation.
rate_limit_exceeded	Too many requests were sent in a short period. Use retry/backoff logic.
service_unavailable	A required upstream dependency is temporarily unavailable. Retry later.
transfer_not_found	The requested transfer does not exist in your organization or environment.
report_not_found	The requested report does not exist in your organization or environment.
quote_request_not_found	The referenced quote request does not exist.
quote_option_not_found	The referenced quote option does not exist.
quote_option_expired	The quote option is no longer valid and must be refreshed.
idempotency_conflict	The same idempotency key was reused with different request parameters.
entity_conflict	The request conflicts with an existing entity or a concurrent change.
customer_webhook_endpoint_limit_exceeded	Your organization has reached the maximum number of configured customer webhook endpoints.
customer_webhook_delivery_replay_unavailable	The delivery cannot be replayed in its current state or the replay window has expired.
crypto_wallet_screening_rejected	A crypto wallet address was blocked by required sanctions screening.
crypto_wallet_screening_unavailable	Heron could not complete required crypto wallet screening. Retry later or contact support.
internal_server_error	An unexpected server-side failure occurred.

Request IDs

Every Heron API response includes an X-Request-Id header. If you contact Heron support about a failed or unexpected request, include this header value along with the endpoint, timestamp, and response error code so support can correlate your report with Heron logs.

Handling Errors

We recommend handling errors by code, not just by HTTP status. For example, if you receive invalid_request, inspect details for field-level information when it is present; if you receive service_unavailable or rate_limit_exceeded, retry with exponential backoff.