{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Errors"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"errors","__idx":0},"children":["Errors"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every non-2xx response from the Tenant Monolith API uses the same envelope."," ","This guide describes the envelope, the status codes you can expect, when"," ","each is returned, and how to handle them."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"response-shape","__idx":2},"children":["Response Shape"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Errors are returned as a JSON object with a single ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," key holding one"," ","or more entries. Each entry has the following fields:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}]}," ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(string, required)"]}," — Machine-readable error type. Stable"," ","across releases and safe to branch on. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#status-codes"},"children":["Status Codes"]}," ","below for the full set."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["detail"]}]}," ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(string, required)"]}," — Human-readable explanation of this"," ","specific occurrence. Intended for logs and developer-facing surfaces; do"," ","not parse."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source"]}]}," ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(object, optional)"]}," — Pointer to the input that caused the"," ","error. Returned for validation errors to identify the offending field;"," ","absent otherwise.",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source.pointer"]}]}," ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(string)"]}," — JSON Pointer path to the offending"," ","attribute, e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/order/package"]},"."]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A single response may include multiple entries when more than one field"," ","fails validation. Non-validation errors return exactly one entry."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"status-codes","__idx":3},"children":["Status Codes"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"401--authorization_error","__idx":4},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authorization_error"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The request did not include a valid bearer token."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"403--forbidden","__idx":5},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["forbidden"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The token is valid, but the caller is not permitted to perform the requested"," ","action."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"404--not_found_error","__idx":6},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not_found_error"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The requested resource does not exist, or it exists but the caller is not"," ","authorized to access it. The two cases are not distinguished, to avoid"," ","leaking the existence of resources owned by other organizations."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"422--validation_error","__idx":7},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validation_error"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The request body or parameters failed validation. The response may include"," ","multiple entries — one per offending field — with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source.pointer"]}," ","identifying the attribute."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"500--internal_error","__idx":8},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internal_error"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An unexpected error occurred while processing the request. Safe to retry."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"authorization-model","__idx":9},"children":["Authorization Model"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Resources are scoped to the authenticated organization. A request for a"," ","resource owned by another organization returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not_found_error"]},","," ","identical to the response for a resource that does not exist. This applies"," ","uniformly to every resource endpoint — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /orders/{id}"]},","," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /reports/{id}"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /orders/{id}/report"]},", and any future read."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"endpoint-specific-404s","__idx":10},"children":["Endpoint-Specific 404s"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some endpoints return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}," for reasons beyond authorization, where the"," ","resource itself is not yet available:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/v1#operation/get-order-report"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /orders/{id}/report"]}]}," — the order"," ","exists but has not yet produced a report (typically because it is still in"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["waiting_for_applicant"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]}," status)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These cases are documented on the individual endpoints."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"examples","__idx":11},"children":["Examples"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A validation error pointing at a specific field:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"errors\": [\n    {\n      \"code\": \"validation_error\",\n      \"detail\": \"must be one of: starter, essential\",\n      \"source\": { \"pointer\": \"/order/package\" }\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}," for a resource that does not exist (or that the caller is not"," ","authorized to access):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"errors\": [\n    {\n      \"code\": \"not_found_error\",\n      \"detail\": \"Report not found\"\n    }\n  ]\n}\n","lang":"json"},"children":[]}]},"headings":[{"value":"Errors","id":"errors","depth":2},{"value":"Overview","id":"overview","depth":3},{"value":"Response Shape","id":"response-shape","depth":3},{"value":"Status Codes","id":"status-codes","depth":3},{"value":"401 — authorization_error","id":"401--authorization_error","depth":4},{"value":"403 — forbidden","id":"403--forbidden","depth":4},{"value":"404 — not_found_error","id":"404--not_found_error","depth":4},{"value":"422 — validation_error","id":"422--validation_error","depth":4},{"value":"500 — internal_error","id":"500--internal_error","depth":4},{"value":"Authorization Model","id":"authorization-model","depth":3},{"value":"Endpoint-Specific 404s","id":"endpoint-specific-404s","depth":3},{"value":"Examples","id":"examples","depth":3}],"frontmatter":{"seo":{"title":"Errors"}},"lastModified":"2026-05-14T17:01:17.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/errors","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}