> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.hopnow.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Error envelope, validation errors, and HTTP status codes

When a request fails, the API returns a JSON object with as much descriptive information as possible. Every error response carries a `request_id` — include it when contacting support.

<ResponseField name="error.type" type="string">
  Error type identifier in snake\_case, e.g. `resource_not_found`, `insufficient_funds`.
</ResponseField>

<ResponseField name="error.code" type="string">
  Machine-readable error code, e.g. `RESOURCE_NOT_FOUND`. Use this for programmatic handling.
</ResponseField>

<ResponseField name="error.message" type="string">
  Human-readable description of what went wrong.
</ResponseField>

<ResponseField name="error.details" type="object | null">
  Additional structured context, when available.
</ResponseField>

<ResponseField name="request_id" type="string | null">
  Identifier of the request, for tracing and support.
</ResponseField>

```json Example — error response theme={null}
{
  "error": {
    "type": "resource_not_found",
    "code": "RESOURCE_NOT_FOUND",
    "message": "Beneficiary not found",
    "details": {
      "beneficiary_id": "bene_j7jd54mlirldky8rb93d99qd"
    }
  },
  "request_id": "req_abc123def456"
}
```

## Validation errors

When a request body fails validation, the response is `422` and includes a `validation_errors` array listing every failed field — not just the first one.

<ResponseField name="validation_errors[].field" type="string">
  The field that failed validation.
</ResponseField>

<ResponseField name="validation_errors[].message" type="string">
  Why the value was rejected.
</ResponseField>

<ResponseField name="validation_errors[].value" type="any">
  The invalid value that was provided.
</ResponseField>

```json Example — validation error (422) theme={null}
{
  "error": {
    "type": "validation_error",
    "code": "VALIDATION_ERROR",
    "message": "Amount must be greater than 0; Invalid currency code"
  },
  "validation_errors": [
    { "field": "amount", "message": "Amount must be greater than 0", "value": -100 },
    { "field": "currency", "message": "Invalid currency code", "value": "XXX" }
  ],
  "request_id": "req_abc123def456"
}
```

## HTTP status codes

| Status | Meaning                                                                                                                                                  |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200`  | Request succeeded.                                                                                                                                       |
| `401`  | Missing or invalid signature, stale timestamp, replayed nonce, or unknown API key.                                                                       |
| `403`  | The API key is not enabled for this API, the request is otherwise not authorized, or a known top-level customer/account belongs to another organization. |
| `404`  | The resource does not exist, or a child resource does not belong to the authorized parent resource in the path.                                          |
| `422`  | The request was understood but failed validation or a business rule.                                                                                     |
| `429`  | Rate limit exceeded. Retry with backoff.                                                                                                                 |