Errors
What each error from the API means, and what to do about it.
Every error answers with JSON. detail is a message for you, the developer; on a 422 it is a list of what is wrong and where. Some errors also carry a code you can act on, and a few add more fields:
{ "detail": "…", "code": "busy", "retry_after_seconds": 3 }Act on the status and the code, never on the text of detail: it can change. A refusal a safety check makes also carries type, error and request_id; see Safety refusals.
Safety refusals
When a safety check refuses a request, the answer keeps every field above and adds three: type, an error object, and a request_id.
{
"detail": "New conversations are paused after repeated violations of our Acceptable Use Policy. Try again in about 2 hours. It covers this end user's conversations.",
"code": "policy_curfew",
"retry_after_seconds": 7200,
"type": "error",
"error": {
"type": "policy_error",
"code": "policy_curfew",
"message": "New conversations are paused after repeated violations of our Acceptable Use Policy. Try again in about 2 hours. It covers this end user's conversations.",
"retry_after_seconds": 7200
},
"request_id": "req_01JC3M5Z8Q4T6V2X9B7N1K0F3D"
}Branch on error.type, then on error.code. Never branch on detail or error.message: their words can change. policy_error means our Acceptable Use Policy review, or its enforcement, stopped the request. invalid_request_error means a fixed limit of the product, so you can fix the request.
To ask us about a refusal, send its request_id to support@nuancelabs.ai. The request-id response header repeats it. A web page on another site cannot read that header, so it reads request_id from the body.
error.code | Status | error.type | Meaning |
|---|---|---|---|
app_review_refused | 400 | policy_error | Our review refused the setup (personality., its tools, or Nuance Live's delegation instructions) under the Acceptable Use Policy. detail says why, and for a restricted area what to remove. |
app_review_held | 400 | policy_error | Your organization has used today's reviews. We review the setup within a day; if it passes, it can start conversations then. |
instructions_refused | 400 | invalid_request_error | The setup asks the persona for something it never does, whatever our review finds: to speak a language other than English (or it has non-English characters) or to name the AI model or company it runs on. Or its tools are too large to review. detail says what to change. |
policy_curfew | 403 | policy_error | New conversations are paused after repeated violations. See Safety. |
organization_paused | 403 | policy_error | New conversations for your organization are paused while we review its use. |
organization_suspended | 403 | policy_error | Your organization is suspended for breaking the Acceptable Use Policy. |
The three 400 refusals have no top-level code; their code is error.code. Every other error keeps the shape at the top of this page, without these fields.
Starting a conversation
These come from POST /conversation:
| Status | code | Meaning | What to do |
|---|---|---|---|
| 400 | The request is not valid, for example one that sets its own personality: a session token's conversation takes it from the token. A safety refusal also names its error. (Safety refusals). | Fix the request, or act on error.. | |
| 400 | prompt_too_long | personality. is longer than this personality takes. max_ is the most it takes. | Shorten the prompt to max_ or fewer. |
| 400 | not_served | The conversation can't be served as it is set up right now. No conversation was created. | Try again later, and write to support@nuancelabs.ai if it keeps happening. |
| 401 | not_authenticated | The token is missing, expired or already used. | Mint a new session token. |
| 401 | api_key_revoked | The API key that minted the token was revoked. | Create a new API key. |
| 403 | api_key_in_browser | An API key was sent from a web page on another site, where anyone who opens the page can read it. | Mint a session token on your server, and give the page that. |
| 403 | organization_suspended | Your organization is suspended for breaking the acceptable use policy. None of its keys or their tokens work, and it can't make new keys. | Write to support@nuancelabs.ai to ask why or to appeal. |
| 403 | organization_paused | New conversations for your organization are paused while we review its use against the acceptable use policy. Its keys still work. | Write to support@nuancelabs.ai if you think it is a mistake. |
| 403 | legal_required | The account that made your API key hasn't accepted the API Developer Agreement and the Acceptable Use Policy, or it failed Nuance's age check. | Sign in to the platform with that account and accept them. Accepting doesn't lift a failed age check. |
| 403 | legal_blocked | The browser starting the conversation with a session token is in a region Nuance isn't offered in (reason region). | Don't offer conversations to people there; the API Developer Agreement doesn't allow it. |
| 403 | policy_curfew | New conversations are paused after repeated violations of our Acceptable Use Policy. Also retry_ and a Retry-After header. | Wait, and see Safety. |
| 409 | concurrency_limit | Your API keys already run as many conversations at once as your plan allows. Also active (how many run) and limit (how many may). | End one first: list your active conversations and end one from your server. |
| 429 | start_limit | Your API keys have started as many conversations in the last hour as your plan allows, ended ones included. Also retry_ and a Retry-After header. | Try again after retry_, when the oldest of them is an hour old. Get your usage shows your hourly_. |
| 429 | credits_spent | Your API keys have used today's credits and any credits we added to your account (what a credit counts). Today's renew at 00:00 UTC; renews_ says when. | Wait for the renewal. Get your usage shows what is left and when it renews. |
| 429 | capacity_unavailable | No capacity can take the conversation within a few seconds. Nothing was started or spent. Also retry_ and a Retry-After header. | Try again after retry_, with the same session token while it is still unused and under 60 seconds old, else with a new one. See When capacity is short. |
| 503 | busy | The service is too busy to create the conversation right now. Also retry_ and a Retry-After header. | Try again after retry_ (3 if absent). |
| 503 | unavailable | The conversation could not be started. No conversation was created. | Try again in a few seconds. |
| 503 | maintenance | The service is under maintenance. detail is a notice you can show as it is. | Try again later. |
Minting a session token
POST /session-tokens answers with:
| Status | code | Meaning |
|---|---|---|
| 400 | The personality is not valid. detail says why. A safety refusal also names its error. (Safety refusals). | |
| 400 | unknown_persona | personality. names no persona you can use. detail lists the ones you can (mira, sam and sonia): send one of them, or leave it out for sam. |
| 400 | reserved_persona | personality. is emma, the Nuance app's own character, which API sessions can't be drawn as. detail lists the ids you can send. |
| 400 | prompt_too_long | personality. is longer than this personality takes. Shorten it to max_ or fewer. |
| 400 | unknown_interface | interface names an interface the service doesn't offer. See Set up a session. |
| 422 | interface_setup | A key or value in interface_ the session can't run; detail names it. See Nuance Live's errors. |
| 422 | expressiveness isn't a number from 0 to 2. detail says where. | |
| 401 | not_authenticated | The API key is missing or wrong. |
| 401 | api_key_revoked | The API key was revoked. Create a new one. |
| 403 | organization_suspended | Your organization is suspended (see above). |
| 403 | organization_paused | New conversations for your organization are paused (see above), so no token is minted. |
| 403 | api_key_in_browser | The request came from a web page on another site. Mint tokens on your server. |
| 403 | api_key_required | The credential is not an API key (nk_). Mint tokens on your server, with an API key. |
| 429 | start_limit | Your API keys have minted as many tokens in the last hour as your plan lets them start conversations (hourly_), so no token is minted. Try again after retry_. |
| 429 | credits_spent | Your API keys have used today's credits and any credits we added to your account, so no token is minted (what a credit counts). Today's renew at 00:00 UTC (renews_); get your usage shows what is left. |
Ending a conversation
POST /conversation/{id}/end answers with:
| Status | code | Meaning |
|---|---|---|
| 403 | api_key_required | The credential is not an API key (nk_). End conversations from your server, with an API key. |
| 404 | The conversation doesn't exist, or it is another organization's. | |
| 503 | unavailable | The conversation couldn't be ended right now, and nothing about it changed. Try again in a few seconds; ending it again is safe. |
Any route
| Status | code | Meaning |
|---|---|---|
| 401 | not_authenticated | The credential is missing or wrong, a session token has expired or was already used, or a token shaped like a JWT is one we can't read or our signing keys don't accept. |
| 401 | api_key_revoked | The API key, or the key that minted the session token, was revoked. |
| 403 | api_key_in_browser | An API key was sent from a web page on another site. API keys are for your server; give the browser a session token. |
| 403 | api_key_required | The route takes an API key (nk_), such as get your usage, and the credential is another kind. |
| 403 | credential_not_allowed | The credential can't call this route, such as a session token on another conversation, or an API key on a route for signed-in people. |
| 403 | organization_suspended | The organization is suspended. |
| 403 | detail "Forbidden": a token shaped like a JWT that we can't check right now. It names a signing key we don't have; our signing keys couldn't be fetched afresh to check it; it was signed with a key we've since replaced, and the server answering saw it replaced; the server answering has held the token's signing keys for less than 10 minutes, so it can't yet tell a token it didn't sign from one of ours; or it is a Nuance sign-in token that has expired or isn't valid yet. API keys (nk_) and session tokens (st_) never get it; send one of those instead. | |
| 404 | The conversation doesn't exist, or your credential can't see it. The API doesn't say which. | |
| 411 | A POST without a Content-Length header. Send Content-Length: 0 when there is no body. | |
| 422 | The request doesn't match the route's shape, such as an end_ with characters it can't hold. detail says where. | |
| 500 | Something went wrong on our side. Try again; tell us if it keeps happening. |
During a conversation
Once the conversation is created, the session reports its own errors as error events on the nuance_live topic, not as HTTP answers. Limits and errors lists them, and session.closed says why a session ended.