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

# Responses and Errors

> Understand Maito API success responses, error envelopes, and status codes.

Maito REST responses use a JSON envelope.

## Success Envelope

A successful response has `ok: true` and a `data` value.

```json theme={null}
{
  "ok": true,
  "data": {}
}
```

`data` can be an object, array, string, number, boolean, or `null`, depending on the endpoint.

## Error Envelope

An error response has `ok: false` and an `error` object.

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request."
  }
}
```

`details` may be included for validation issues or structured domain context:

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request.",
    "details": []
  }
}
```

## Status Codes

| Status | Meaning                                                                              |
| ------ | ------------------------------------------------------------------------------------ |
| `400`  | The request body, query, or path parameter is malformed.                             |
| `401`  | The API key is missing, invalid, or expired.                                         |
| `403`  | The key is valid, but the caller cannot access the requested resource or capability. |
| `404`  | The resource was not found.                                                          |
| `409`  | The request conflicts with current state.                                            |
| `422`  | The request was readable but failed validation or domain rules.                      |
| `429`  | The client is sending requests too quickly.                                          |
| `500`  | Server error or server misconfiguration.                                             |

## Common Error Codes

| Code                   | Meaning                                                                |
| ---------------------- | ---------------------------------------------------------------------- |
| `UNAUTHORIZED`         | Authentication is required or invalid.                                 |
| `VALIDATION_ERROR`     | Request input failed validation.                                       |
| `NOT_FOUND`            | The requested resource does not exist or is not visible to the caller. |
| `CONFLICT`             | The operation conflicts with current resource state.                   |
| `SERVER_MISCONFIGURED` | The server is missing required configuration.                          |

Exact domain error codes can vary by endpoint. Clients should branch on HTTP status first, then use `error.code` for product-specific handling.

## Retry Guidance

| Status | Retry?                                                   |
| ------ | -------------------------------------------------------- |
| `400`  | No. Fix the request.                                     |
| `401`  | No. Create or provide a valid API key.                   |
| `403`  | No. Check permissions or account access.                 |
| `404`  | Usually no. Verify the resource ID or path.              |
| `409`  | Retry only after changing the request or resource state. |
| `422`  | No. Fix the request data.                                |
| `429`  | Yes, after waiting.                                      |
| `500`  | Yes, with exponential backoff.                           |