Troubleshooting · Falcon docs

When something is refused, the answer is a problem with a code, a title and a request_id. Find the code on this page. Every answer also carries an X-Request-Id header with the same id: give it to support and they can find exactly what happened.

{
  "type": "about:blank",
  "title": "Permission denied",
  "status": 403,
  "code": "permission_denied",
  "request_id": "req_7Hc2xQ"
}

Code	Status	What it means	What to do
`invalid_request`	400 Invalid request	Something in the request is missing or not in the right form.	Check the fields against the API reference. The problem's `field` and `reason`, when present, say which one.
`unauthenticated`	401 Unauthenticated	You are not signed in, or your sign-in has ended.	Sign in again. An assistant connected over MCP signs in again through your browser.
`permission_denied`	403 Permission denied	You are signed in, but your role does not allow this, or an assistant's access does not include it.	Ask an administrator to check your role in Company settings › Roles. For an assistant, reconnect it and allow the access it needs.
`step_up_required`	403 step up required	This change needs you to confirm it's you first, with your second step.	Confirm with your authenticator app, passkey or code, then try again.
`not_found`	404 Not found	What you asked for does not exist in this company, or you cannot see it.	List what is there now and use one of those. Someone may have deleted or moved it.
`unknown_host`	404 Unknown host	The address you used does not belong to a company.	Check your company's address, the one you sign in at.
`idempotency_conflict`	409 Idempotency conflict	The same request key was used before for a different request.	Use a new `Idempotency-Key` for a new request. Reuse a key only to repeat exactly the same request.
`in_use`	409 in use	This cannot be deleted because something still uses it.	The problem's `used_by` lists what uses it that you can open. Change or remove those first.
`reply_route_unavailable`	409 reply route unavailable	The way to send this reply is not available right now.	Check the connection it uses under Connections, then try again.
`stale_revision`	412 Stale revision	Someone changed this after you read it.	Read it again, look at what changed, then make your change on the new version.
`exception_document_invalid`	422 exception document invalid	The Exceptions graph or named kinds failed validation; nothing was saved.	Correct the messages in `problems`. A `step_id`, when present, identifies the node to edit. Save against the current revision.
`reply_route_denied`	422 reply route denied	A reply was sent to an address this agent may not reply from.	Check which addresses the agent may use in its channels.
`sender_field_refused`	422 sender field refused	A sender or identity field was refused, for example because it could be mistaken for someone else.	The problem's `field` and `reason` say which field and why. Change that field and save again.
`precondition_required`	428 Precondition required	A change needs to say which version it changes.	Read the current version and send its revision in the `If-Match` header.
`rate_limited`	429 rate limited	Too many requests in a short time.	Wait a little and try again. The `Retry-After` header says how long, when it is sent.
`usage_limit_reached`	429 The monthly limit for Ask Studio and MCP calls is reached, or an administrator has paused them. An administrator can change this under Reports › Studio assistant and MCP.	A monthly cap for you or for this assistant has been reached, or an administrator paused assistant use.	Ask an administrator to raise the cap or turn assistant use back on in Reports › Costs.
`internal_error`	500 Internal error	Something went wrong on our side. Nothing was changed unless the result says so.	Check the current state before you try a change again, and contact support with the request id.
`not_implemented`	501 not implemented	This is designed but not built on this host yet.	Check the feature's status on its guide. Coming next features answer this until they are built.
`provider_unavailable`	503 provider unavailable	A service this depends on is not available right now, or it is not switched on for your company.	Try again later. If it keeps happening, contact support with the request id.
`auth_failed`		A mailbox or service refused the sign-in details for a connection.	Check the connection's details under Connections and connect it again.
`domain_claimed`		Another company already uses this domain, its parent or a subdomain.	Ask to join that company, or ask an administrator to review the domain ownership.
`domain_consumer`		Personal email domains cannot be trusted work domains.	Use a work domain the company owns and can prove through DNS.
`domain_paused`		Trust for this work domain is paused, unproved or needs a fresh proof check.	Ask an administrator to check the DNS proof. A lapsed proof needs explicit re-approval; old people are not restored automatically.
`email_unverified`		The email address has not been confirmed yet.	Open the confirmation email and follow its link, then try again.
`identity_code_taken`		Another identity already uses this code.	Choose a different code.
`identity_code_unbound`		This identity code is not linked to anyone yet.	Link it on the identity's page first.
`identity_code_unknown`		No identity has this code.	Check the code on the identity's page.
`imap_auth_failed`		The mailbox refused the sign-in for reading mail.	Check the mailbox user name and password, or app password, and connect it again.
`imap_unavailable`		The mailbox could not be reached for reading mail.	Check the mailbox server address and port, then try again later.
`kind_human_mismatch`		The human flag disagrees with the identity kind.	Use true for a person and false for a place (unit in the API), or omit is_human and let the server derive it. The flag does not grant verification or consent.
`likeness_refused`		A picture or video tool refused: the model tried to choose a picture, look, model or seed; a real person's likeness has no current consent; or a rating does not fit.	The problem's `field` and `reason` say which. Record consent on the identity's Likeness, pick a look that fits the rating, or leave pictures to the look and identity.
`message_held`		The safety check held this message because of what it says, so it was not sent.	Change the wording and send it again.
`model_keeps_data_not_allowed`		The agent's model may keep data, and your company has not allowed models that may. Nothing about your role needs to change.	An administrator can turn on Allow models that may keep data (Dev only) in Connections › Model providers, or the agent can be switched to a model that keeps nothing.
`model_not_allowed`		The selected test model is not approved by the company or does not meet the agent's data handling and the company's retention policy.	Choose an approved model that meets those settings. A paused test keeps the model it started with; use a new test to compare another model.
`number_not_in_inventory`		This number is not in the company's Numbers inventory.	An owner or administrator adds it on the Numbers page before assigning it.
`number_not_usable`		This inventory number cannot be assigned in its current state.	Read the reason and refresh the Numbers page. To move an owned number or rescue a parked number, confirm a reallocation. A release that has started cannot be cancelled.
`relay_denied`		The mail server would not send this message on your behalf.	Check the sending settings with whoever runs the mail server.
`run_not_finished`		The run has not finished, so it has no final text yet.	Follow the run's events, or ask again in a moment.
`screening_unavailable`		The message screening a test message must pass is not switched on in this environment, so the message was not sent.	Ask whoever runs this Studio to switch message screening on. Nothing about your role needs to change.
`stream_unavailable`		This host cannot follow runs as they happen right now. The run itself is not affected.	Try again shortly; the run's result stays readable once it finishes.
`tls_required`		A mail server was reached without a secure connection.	Use the server's secure port or turn on TLS in the connection.