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.
`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.
`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.
`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.
`relay_denied`		The mail server would not send this message on your behalf.	Check the sending settings with whoever runs the mail server.
`tls_required`		A mail server was reached without a secure connection.	Use the server's secure port or turn on TLS in the connection.