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

# Errors

> Handle Arbol API errors, validation details, authorization failures, and request correlation.

API errors contain a stable `code`, an operator-facing `message`, and optional structured `data`. Procedure errors can also include `status`, `defined`, and `inferable` fields described by the generated schema.

```json theme={null}
{
  "defined": true,
  "inferable": true,
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "Input validation failed",
  "data": {
    "issues": [
      {
        "path": ["limit"],
        "message": "Too big: expected number to be <=100"
      }
    ],
    "truncated": false
  }
}
```

## Common status codes

| Status | Meaning                                                                               | Client action                                                   |
| ------ | ------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `400`  | The request could not be decoded or did not match the input schema.                   | Correct the request. Do not retry unchanged.                    |
| `401`  | The bearer credential is missing, invalid, expired, or unusable for this environment. | Obtain a valid credential.                                      |
| `403`  | The verified actor lacks one or more required permissions.                            | Request the missing authority or choose another operation.      |
| `404`  | The resource does not exist in the verified organization or is not visible.           | Confirm the identifier and tenant context.                      |
| `409`  | Current state conflicts with the requested mutation.                                  | Read current state and reconcile revisions or idempotency keys. |
| `413`  | The transport body exceeds its byte limit.                                            | Reduce the request body.                                        |
| `415`  | The request media type is unsupported.                                                | Use the media type declared by OpenAPI.                         |
| `422`  | The request is syntactically valid but violates a domain rule.                        | Correct the referenced resource or domain value.                |
| `429`  | A rate limit was reached.                                                             | Wait for `data.retryAfterSeconds` when present.                 |
| `503`  | A required downstream capability is temporarily unavailable.                          | Retry only when the operation is safe; use backoff.             |

Every API response includes `X-Request-Id`. Log that value with the operation ID and HTTP status, but never with bearer credentials or private payloads.