Reference
Every Org API error response carries one of these code values in its JSON body,
alongside the matching HTTP status. This table is generated from
OrgApiErrorCode in apps/web/src/lib/org-api/responses.ts; it can't drift
out of sync with the API.
| Code | HTTP status | Meaning |
|---|---|---|
| MISSING_API_KEY | 401 | No Authorization/x-api-key header supplied. |
| INVALID_API_KEY | 401 | Key malformed or no bcrypt match. |
| REVOKED_API_KEY | 401 | Key revoked, outside rotation grace window. |
| EXPIRED_API_KEY | 401 | Key is past its expiresAt. |
| IP_NOT_ALLOWED | 403 | Caller IP isn't in the key's IP allowlist. |
| BILLING_ACCESS_DENIED | 402 | Org's billing/access level blocks this route. |
| INSUFFICIENT_SCOPE | 403 | Key is missing a required scope for this operation. |
| FORBIDDEN | 403 | Generic authorization failure (e.g. author-only edit). |
| RATE_LIMITED | 429 | Rate-limit bucket exceeded; see Retry-After header. |
| QUOTA_EXCEEDED | 402 | A route-specific quota check failed. |
| VALIDATION_FAILED | 400 | Request body failed Zod/shape validation. |
| NOT_FOUND | 404 | Resource not found, or belongs to another organization. |
| CONFLICT | 409 | Generic conflict with existing state. |
| IDEMPOTENCY_REQUIRED | 400 | Idempotency-Key header missing on a mutating request that requires it. |
| IDEMPOTENCY_CONFLICT | 409 | Same Idempotency-Key replayed with a different request body. |
| OWNERSHIP_REQUIRED | 400 | Missing or invalid owner assignment on a created resource. |
| EXTERNAL_REFERENCE_CONFLICT | 409 | An External Reference tuple already points at a different resource. |
| SEAT_LIMIT_REACHED | 409 | Creating a schedulable team member would exceed the included technician seats; requires an interactive org-admin action. |
| AURORA_IDENTIFIERS_REQUIRED | 400 | Aurora sync request is missing design/project identifiers. |
| CUSTOM_FIELD_VALIDATION_FAILED | 400 | customFields payload fails the tenant Field contract. |
| UNSUPPORTED_PROJECT_TEMPLATE | 400 | Template can't safely apply (e.g. FROM_QUOTE-only fields). |
| UNSUPPORTED_SORT | 400 | Invalid sortBy/sortDir combination. |
| UNSUPPORTED_FILTER | 400 | Invalid or unsupported query filter. |
| INTERNAL_ERROR | 500 | Uncaught exception — treat as a solarOS bug, retry with backoff. |
Was this page helpful?