> ## 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

> Handle one structured JSON error envelope across OrgX REST API v1.

Errors use one envelope:

```json theme={"dark"}
{
  "error": {
    "code": "validation_failed",
    "message": "Title is required",
    "details": { "field": "title" },
    "requestId": "req_01J5YB8X4Y",
    "timestamp": "2026-08-18T18:30:00.000Z"
  }
}
```

Branch on the HTTP status and `error.code`. When `requestId` is present, log it
and include it when you contact support.

| Status | Meaning | Retry |
| - | - | - |
| `400` | Invalid request | Fix the request |
| `401` | Missing or invalid authentication | Fix or rotate the key |
| `403` | The caller lacks permission | Change scope or access |
| `404` | The resource is unavailable in this workspace | Check the ID and workspace |
| `409` | State or idempotency conflict | Read current state before deciding |
| `413` | Request exceeds the documented size | Reduce the body |
| `422` | The JSON fails the resource schema | Fix the reported issue paths |
| `424` | An upstream service failed or timed out | Retry reads; retry writes with the same key |
| `429` | Rate limit reached | Honor `Retry-After` |
| `500` | Unexpected server error | Retry only with an idempotency key |
| `503` | Temporarily unavailable, or out of time | Back off and retry |

OrgX never responds with `502` or `504`: those statuses are rewritten by the
network edge and would hide the error body. Upstream failures use `424` and
deadlines use `503`, both with the error envelope below.

Validation endpoints may add bounded `issues` with JSON Pointer paths. The
outer `error` envelope remains the programmatic contract.

## Error codes

Codes are lowercase `snake_case`. The shared vocabulary is:

| Code | Status | Meaning |
| - | - | - |
| `bad_request` | 400 | The request format is invalid |
| `validation_failed` | 400 | The request failed schema validation |
| `unauthorized` | 401 | Auth is missing or invalid |
| `forbidden` | 403 | The caller lacks permission |
| `not_found` | 404 | The resource does not exist here |
| `conflict` | 409 | State conflict |
| `budget_exceeded` | 402 | Autonomy budget depleted |
| `plan_limit_reached` | 403 | Plan quota exceeded |
| `rate_limited` | 429 | Too many requests |
| `internal_error` | 500 | Unexpected server error |
| `integration_error` | 424 | An external service failed |
| `service_unavailable` | 503 | A dependency is unavailable |
| `timeout` | 503 | The request timed out |
| `missing_idempotency_key` | 400 | A mutation did not include `Idempotency-Key` |
| `idempotency_key_conflict` | 409 | The key was reused with a different payload |
| `lifecycle_action_failed` | 422 | The requested lifecycle transition was refused |

Individual resources add their own codes on top of these — for example
`missing_idempotency_key`, `handoff_conflict`, `operating_process_conflict`,
`discovery_run_in_progress`, `invalid_agent_work_receipt`, and
`direct_human_decision_action_required`. Mutations also use
`idempotency_key_conflict` for retry protection. Those are documented on each
resource's page. Branch on the HTTP status first and the code second, so an
unfamiliar resource-specific code still routes to the right handling.

## The MCP tool surface uses a different vocabulary

MCP tool errors are **not** these codes. That surface has its own set —
`invalid_input`, `auth_required`, `permission_denied`, `entity_not_found`,
`stale_version`, `rate_limit_exceeded`, `server_error`, and others —
documented in the [failure playbooks](https://docs.useorgx.com/docs/agent-ops/failure-playbooks.md). The two
vocabularies are not aliases of each other; do not map one onto the other in
client code.

| Condition | REST v1 | MCP tools |
| - | - | - |
| Validation failed | `validation_failed` | `invalid_input` |
| Auth missing or invalid | `unauthorized` | `auth_required` |
| Caller lacks permission | `forbidden` | `permission_denied` |
| Resource not found | `not_found` | `entity_not_found` |
| Concurrency conflict | `conflict` (or a resource-specific `*_conflict`) | `stale_version` |
| Rate limited | `rate_limited` | `rate_limit_exceeded` |
| Unexpected server error | `internal_error` | `server_error` |

Retry timing differs with the surface too: REST v1 sends `Retry-After`; the
MCP edge sends `X-RateLimit-Reset` alongside `X-RateLimit-Limit` and
`X-RateLimit-Remaining`. Honor whichever the response you are holding carries.


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