Errors

Every error response uses a single envelope shape:

{
  "error": {
    "code": "validation_error",
    "message": "request validation failed",
    "requestId": "0190abcd-1234-7000-8000-000000000000",
    "details": [{ "path": "name", "message": "Required" }]
  }
}

• code — a stable machine-readable code (table below).
• message — a human-readable description.
• requestId — the request correlation id, also returned as the X-Request-Id header (see Request IDs).
• details — present on validation errors; an array of { path, message } field issues.

Codes

| code | HTTP | Meaning | | --- | --- | --- | | unauthenticated | 401 | Missing or invalid API key. | | tenant_suspended | 402 | The tenant's billing is suspended. | | forbidden | 403 | The key lacks the required permission. | | not_found | 404 | The resource does not exist. | | validation_error | 400 | The request body or query failed validation. | | invalid_company | 422 | No valid company resolved (see Company scoping). | | conflict | 409 | A state/version conflict. | | idempotency_conflict | 409 | Same Idempotency-Key, different request. | | idempotency_in_progress | 409 | A request with this key is still processing. | | rate_limited | 429 | Per-key rate limit exceeded (see Rate limits). | | internal_error | 500 | An unexpected server error. |