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

# Error Codes

> Encountered an error? This page explains Hyperrial API error codes, what they mean, and how to resolve them.

## Hyperrial API Response Codes

Hyperrial uses standard HTTP response codes to communicate the outcome of API requests. Always inspect both the **HTTP status code** and the **response body** to fully understand what happened.

### Success (2xx)

* **200 OK**\
  The request was processed successfully.\
  ⚠️ Always inspect the response payload to confirm the actual transaction state.

* **201 Created**\
  A new resource was successfully created (e.g., transactions, accounts, or configurations).

***

### Client Errors (4xx)

* **400 Bad Request**\
  The request is malformed or missing required parameters.\
  ✔️ Validate request payloads and data types.

* **401 Unauthorized**\
  Authentication failed due to a missing or invalid API key.\
  ✔️ Ensure your API key is included in the `Authorization` header.

* **403 Forbidden**\
  The API key does not have permission to perform the requested action.\
  ✔️ Verify the key’s scope or assigned role.

* **404 Not Found**\
  The requested resource does not exist or the endpoint is incorrect.

* **429 Too Many Requests**\
  Rate limit exceeded.\
  ✔️ Implement retry logic with exponential backoff.

***

### Server Errors (5xx)

* **500, 502, 503, 504**\
  These indicate internal server errors on Hyperrial’s infrastructure.\
  ✔️ Treat the outcome as inconclusive and retry later.\
  ✔️ If persistent, contact support.

***

## Error Handling Best Practices

Beyond HTTP status codes, Hyperrial responses may include structured error objects with additional context such as error type, message, and resolution hints.

### General Guidelines

* **Do Not Assume Outcomes**\
  Network or timeout errors may leave the transaction state unknown.

* **Rely on Webhooks**\
  Webhooks provide authoritative confirmation of transaction outcomes and should be treated as the source of truth.

***

## Common Error Types

| Error Type                | Description                                                        | Recommended Action                                            |
| ------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------- |
| **Invalid Request Error** | Request parameters are invalid, missing, or incorrectly formatted. | Review endpoint documentation and fix request payloads.       |
| **Authentication Error**  | API key is missing, invalid, or inactive.                          | Verify the API key and authorization headers.                 |
| **Permission Error**      | API key lacks the required permissions.                            | Use a key with appropriate access or update role permissions. |
| **Rate Limit Error**      | Too many requests sent within a short timeframe.                   | Implement retries with backoff or request higher limits.      |
| **Connection Error**      | Temporary network or connectivity issue.                           | Retry safely and rely on webhooks for final status.           |
| **Server Error**          | Internal error on Hyperrial’s side.                                | Retry later and monitor webhook events.                       |

***

By properly handling these errors and relying on webhooks for final state confirmation, you can build **resilient, fault-tolerant integrations** with the Hyperrial API.