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

# Errors

> How the API returns and structures errors

## Overview

Our API uses standard HTTP status codes to indicate whether a request was successful or failed. While HTTP codes provide a high-level summary, we also return a structured JSON error object with descriptive fields so you can programmatically detect, log, and handle specific error cases.

**In general:**

* **2xx** — The request succeeded.
* **4xx** — The request failed due to a problem with the information provided (e.g., missing a required parameter, invalid value, business rule violation).
* **5xx** — A problem occurred on our servers or with an upstream dependency (rare).

## Error Response Format

When an error occurs, the response body includes a JSON object containing details about the error:

| Field        | Type                  | Description                                                                                                                                    |
| ------------ | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`       | `string`              | A short string classifying the error. Possible values: `api_error`, `validation_error`, `auth_error`, `idempotency_error`, `rate_limit_error`. |
| `code`       | `string` *(nullable)* | A programmatic code identifying the specific error.                                                                                            |
| `message`    | `string` *(nullable)* | A human-readable message explaining the error. Suitable for displaying to users where appropriate.                                             |
| `param`      | `string` *(nullable)* | The parameter related to the error, if applicable.                                                                                             |
| `doc_url`    | `string` *(nullable)* | A link to relevant documentation for this error type.                                                                                          |
| `request_id` | `string` *(nullable)* | An internal request identifier for troubleshooting with support.                                                                               |

**Example**

```json theme={null}
{
  "error": {
    "type": "validation_error",
    "code": "missing_required_field",
    "message": "The 'amount' field is required.",
    "param": "amount",
    "doc_url": "https://docs.mansa.io/errors/missing_required_field",
    "request_id": "req_123456789"
  }
}
```

## HTTP Status Code Summary

| Code                          | Meaning                | Notes                                                                  |
| ----------------------------- | ---------------------- | ---------------------------------------------------------------------- |
| **200 OK**                    | Success                | Everything worked as expected.                                         |
| **400 Bad Request**           | Invalid request        | Missing or invalid parameters.                                         |
| **401 Unauthorized**          | Authentication error   | No valid API key or token provided.                                    |
| **403 Forbidden**             | Permission error       | API key lacks required permissions.                                    |
| **404 Not Found**             | Resource not found     | The requested resource does not exist.                                 |
| **409 Conflict**              | Request conflict       | Likely due to duplicate or conflicting data.                           |
| **422 Unprocessable Entity**  | Validation error       | Request parameters are syntactically correct but semantically invalid. |
| **429 Too Many Requests**     | Rate limit exceeded    | Slow down and retry with exponential backoff.                          |
| **500 Internal Server Error** | Server error           | Something went wrong on our end.                                       |
| **502 Bad Gateway**           | Upstream service error | Temporary issue with dependencies.                                     |
| **503 Service Unavailable**   | Temporary outage       | Try again later.                                                       |
| **504 Gateway Timeout**       | Timeout                | Upstream service took too long to respond.                             |

## Error Types

| Type                   | Description                                          |
| ---------------------- | ---------------------------------------------------- |
| **api\_error**         | Catch-all for unexpected server errors.              |
| **validation\_error**  | Invalid request parameters or data.                  |
| **auth\_error**        | Missing or invalid authentication credentials.       |
| **idempotency\_error** | Idempotency key reused with mismatched request data. |
| **rate\_limit\_error** | Request rate exceeded the allowed limit.             |

## Best Practices for Handling Errors

* **Log the full error object** for troubleshooting.
* **Handle `4xx` errors programmatically** where possible (e.g., show the `message` to the user if it’s safe to do so).
* **Implement retries with exponential backoff** for `5xx` or `429` errors.
* **Use `param`** to highlight specific fields in form validation errors.
* **Monitor error rates** to detect systemic issues early.

***

**Related guide:** [Error Handling](../guides/error-handling)