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

# Errors

> Error codes and handling for the Qubrics Mailbox API.

The Mailbox API uses standard HTTP status codes and the same error envelope as the Management API.

## Error response format

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "invalid_parameter",
    "message": "A human-readable description of the error.",
    "param": "cursor",
    "doc_url": "https://qubrics.com/docs/api/errors#invalid_parameter",
    "retryable": false
  },
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}
```

| Field | Description |
| - | - |
| `code` | Stable machine-readable code. Branch client logic on this value. |
| `message` | Human-readable description. Wording may change. |
| `param` | Present when the error maps to a specific request field. |
| `doc_url` | Link to the error reference. |
| `retryable` | `true` when the same request may succeed later without changes. |
| `errors` | Present on accumulated validation failures. |

## Common codes

| HTTP status | Error code | Retryable | Meaning |
| - | - | - | - |
| `400` | `invalid_parameter` | false | Bad query parameter or malformed request body. |
| `400` | `missing_parameter` | false | Required parameter missing. |
| `401` | `authentication_required` | false | Missing, invalid, expired, or revoked API key. |
| `403` | `insufficient_permissions` | false | The key is valid but cannot call this endpoint. |
| `404` | `not_found` | false | The mailbox or requested resource is absent or inaccessible. |
| `409` | `conflict` | false | The resource state prevents the operation. |
| `409` | `idempotency_conflict` | false | An `Idempotency-Key` was reused with a different request. |
| `413` | `payload_too_large` | false | The request body is too large. |
| `422` | `validation_error` | false | The request parsed correctly but violates a semantic rule. |
| `429` | `rate_limit_exceeded` | true | Rate limit hit. Honour `Retry-After`. |
| `500` | `internal_error` | true | Unexpected server error. |
| `503` | `service_unavailable` | true | A required service is temporarily unavailable. Honour `Retry-After` when present. |

## Retry handling

Retry only when `retryable` is `true`. For `429` and `503`, use the `Retry-After` header before retrying.

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json
```

For POST requests that support `Idempotency-Key`, send a unique key so a retry cannot perform the same operation twice.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.