> ## 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

> How to handle API errors

## Error Response Format

All errors return a consistent JSON structure:

```json theme={null}
{
  "error": {
    "type": "validation_error",
    "code": "invalid_request",
    "message": "The currency field is required"
  },
  "request_id": "req_a1b2c3d4e5f6"
}
```

`request_id` is a top-level field alongside `error`, and is present on every error response. Include it when contacting support.

## HTTP Status Codes

| Code  | Description                          |
| ----- | ------------------------------------ |
| `200` | Success                              |
| `201` | Created                              |
| `400` | Bad Request - Invalid parameters     |
| `401` | Unauthorized - Authentication failed |
| `403` | Forbidden - Insufficient permissions |
| `404` | Not Found - Resource doesn't exist   |
| `409` | Conflict - Resource already exists   |
| `422` | Unprocessable - Business logic error |
| `429` | Rate Limited - Too many requests     |
| `500` | Server Error - Internal issue        |

## Error Types

| Type                   | Description                  |
| ---------------------- | ---------------------------- |
| `authentication_error` | Invalid API key or signature |
| `authorization_error`  | Insufficient permissions     |
| `validation_error`     | Invalid request parameters   |
| `not_found_error`      | Resource not found           |
| `conflict_error`       | Duplicate resource           |
| `rate_limit_error`     | Too many requests            |
| `api_error`            | Internal server error        |

## Common Errors

### Authentication Failed

```json theme={null}
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_signature",
    "message": "The request signature is invalid"
  }
}
```

**Solution**: Check your HMAC signature calculation.

### Validation Error

```json theme={null}
{
  "error": {
    "type": "validation_error",
    "code": "missing_field",
    "message": "The amount field is required"
  }
}
```

**Solution**: Include all required fields in your request.

### Rate Limited

```json theme={null}
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds"
  }
}
```

**Solution**: Implement exponential backoff and retry logic.

## Error Handling Best Practices

```python theme={null}
try:
    response = client.post("/v1/transfers/payouts", data)
    return response.json()
except APIError as e:
    if e.type == "rate_limit_error":
        time.sleep(60)
        return retry_request()
    elif e.type == "validation_error":
        log_validation_error(e.message)
        return None
    else:
        raise
```