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

# Errors

> OrgX REST and MCP error conventions.

OrgX APIs return standard HTTP status codes with JSON bodies. Preview REST
endpoints may use either a simple error shape or the richer structured error
shape used by newer route handlers.

## HTTP Status Codes

| Code  | Meaning                                      |
| ----- | -------------------------------------------- |
| `200` | Success                                      |
| `201` | Created                                      |
| `400` | Invalid request or validation error          |
| `401` | Missing, invalid, or revoked authentication  |
| `403` | Authenticated, but not permitted             |
| `404` | Resource not found in the caller's workspace |
| `409` | Conflict or invalid resource state           |
| `429` | Rate limited                                 |
| `500` | Internal server error                        |
| `502` | Upstream integration error                   |
| `504` | Query or upstream timeout                    |

## Simple Error Shape

Some preview endpoints return a compact body:

```json theme={"dark"}
{
  "error": "Unauthorized",
  "message": "Valid API key required. Get your key from OrgX settings."
}
```

## Structured Error Shape

Newer endpoints return a structured object:

```json theme={"dark"}
{
  "error": {
    "code": "not_found",
    "message": "Task 2f7b2f47-2d7a-4d65-81d0-5c4b0f9b7e01 not found",
    "status": 404,
    "request_id": "req_01h..."
  }
}
```

## Fields

| Field              | Type             | Description                                     |
| ------------------ | ---------------- | ----------------------------------------------- |
| `error`            | string or object | Human-readable error or structured error object |
| `message`          | string           | Additional human-readable context               |
| `error.code`       | string           | Machine-readable error code                     |
| `error.status`     | number           | HTTP status code                                |
| `error.request_id` | string           | Support and trace identifier                    |

## Retrying Errors

| Status | Retry?     | Guidance                                                               |
| ------ | ---------- | ---------------------------------------------------------------------- |
| `400`  | No         | Fix the request body or query params.                                  |
| `401`  | No         | Rotate or replace the API key.                                         |
| `403`  | No         | Check workspace access and scopes.                                     |
| `404`  | Usually no | Confirm the resource belongs to the API key's workspace.               |
| `409`  | Depends    | Re-read the resource state before retrying.                            |
| `429`  | Yes        | Back off and retry after the reset window.                             |
| `500`  | Yes        | Retry with an idempotency key for writes.                              |
| `504`  | Yes        | Retry reads; retry writes only when the endpoint supports idempotency. |