Foundations
NQD API errors and request IDs
Every failed request returns a safe error object with a request ID.
Resource errors have an error object containing code, message, and requestId. Invalid input may also include error.details.issues, each with a field path and safe validation reason. Responses omit stack traces, SQL, provider responses, and credentials. Use requestId when reporting a failure. When the transport supplies x-request-id, it identifies the same request and should be retained with the error.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_input | Invalid scope, query, body, or domain input |
| 400 | query_invalid | Query field, operator, projection, cursor, or limit is unsupported; details.issues identifies the rejected path |
| 401 | unauthenticated | Missing or invalid bearer; WWW-Authenticate is Bearer |
| 403 | forbidden | Current membership/permission denied |
| 403 | plan_limit | Existing finance/seat/entitlement limit denied |
| 403 | cors_forbidden | Origin is outside the configured API caller list |
| 404 | not_found | Unknown route or scoped target |
| 409 | conflict | Stale edit, conflict, or frozen record |
| 429 | rate_limited / request_quota | Finite rate or external allowance exhausted; Retry-After supplied |
| 503 | unavailable | Dependency or admission unavailable; fails closed |
| 500 | internal_error | Sanitized unexpected failure |
An unsupported method returns 405 with Allow. Successful bodyless deletes return 204. Auth uses its generated sanitized credential errors. Do not infer authorization from an HTTP array or a successful related page.