{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-developer/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Errors","description":"Read US healthcare contracts and organizations, and work with your saved work, from your own code.","siteUrl":"https://docs.hrcledger.com","llmstxt":{"title":"HRC Ledger API","description":"One key, one envelope, every route and guide."}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"errors","__idx":0},"children":["Errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every call that fails answers in the same shape:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"ok\": false,\n  \"error\": {\n    \"code\": \"insufficient_scope\",\n    \"message\": \"This API key is missing the required 'lists:read' scope (read your Lists and their rows, and download them).\",\n    \"scope\": \"lists:read\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," is short and never changes. Write your code against it."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}," is one plain sentence for a person to read. Its words may change."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Some codes add a field, such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["resets_in_seconds"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["current"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every answer has an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Request-Id"]}," header, even a failed one. Tell us that id if"," ","you ask for help with a call."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"every-code-and-what-to-do","__idx":1},"children":["Every code, and what to do"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What it means"},"children":["What it means"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What to do"},"children":["What to do"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["missing_or_malformed_key"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No key was sent, or the header is not ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer <key>"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Send the header with the word ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Bearer"]},", a space, then the whole key."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_key"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The key is not known. It may be revoked, or copied wrong."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check you copied the whole key. Make a new key if it was revoked."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["insufficient_scope"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The key does not have the scope this call needs. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.scope"]}," names it."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Make a key with that scope. A key's scopes cannot be changed after it is made."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["person_required"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The call tried to decide a change the assistant proposed. Only a person in the app can."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Open the link in the app and decide there."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not_found"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Nothing with that id exists, or it belongs to another account."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check the id. Ids come from a list or read call."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["revision_conflict"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Someone changed the work after you read it. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.current"]}," holds the newer version."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.current"]},", make your change to it, and send it again."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["step_changed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["That step changed after you read it."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read the plan again, then send the change."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idempotency_conflict"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["You sent an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]}," you used before, with a different body."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use a new key for a new request. Reuse a key only to retry the same request."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conversation_busy"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The assistant is still answering in that conversation."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Wait for that answer, then ask again."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paused"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Assistant work is paused for now. Nothing is wrong with your call."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Try again later."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_query"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A query parameter did not make sense, such as a bad date."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read the message, fix the parameter, and send it again."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_request"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The body did not make sense, or it has a field the route does not take."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read the message, fix the body, and send it again."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["thread_too_long"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The conversation is too long to carry on."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Start a new conversation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rate_limited"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The key made too many calls."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Wait for the seconds in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Retry-After"]}," header, then try again."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["budget_exhausted"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The assistant has used all it may spend today."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Try again after the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Retry-After"]}," header's seconds."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["503"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["database_unavailable"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The API cannot reach its data right now."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Try again in a little while."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["503"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["model_unavailable"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The assistant could not answer right now."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Try again in a little while."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"retry-safely","__idx":2},"children":["Retry safely"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A call that changes work takes an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]}," header. Send the same key and"," ","the same body to retry, and the work is done once, not twice."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}," or a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["503"]}," after a wait. Do not retry a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}," ","without a change; it fails the same way again."]}]},"headings":[{"value":"Errors","id":"errors","depth":1},{"value":"Every code, and what to do","id":"every-code-and-what-to-do","depth":2},{"value":"Retry safely","id":"retry-safely","depth":2}],"frontmatter":{"seo":{"title":"Errors"}},"lastModified":"2026-10-22T07:39:08.493Z","pagePropGetterError":{"message":"","name":""}},"slug":"/developer/errors","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}