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 an error with Heron's servers (these are rare).

Error Response Body

When an error occurs, the API returns a JSON response body containing the specific error details:

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

Error Codes

Code	Description
invalid_request	The request was unacceptable, often due to missing a required parameter.
unauthorized	No valid API key was provided.
forbidden	The API key doesn't have permissions to perform the request.
not_found	The requested resource doesn't exist.
conflict	The request conflicts with another item (e.g., duplicate idempotency key).
rate_limit_exceeded	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
transfer_not_found	The requested transfer resource was not found.
idempotency_conflict	A request with this idempotency key has already been processed with different parameters.
internal_server_error	Something went wrong on Heron's end.

Handling Errors

We recommend building your integration to handle specific error codes. For example, if you receive invalid_request, you might want to inspect the details field for more information.