Errors

Every error the API can send, grouped by what went wrong. Each error’s type link opens its own page here, with what it means and what to do.

What every error looks like

Every error is a JSON object with the same fields, sent as application/problem+json with the HTTP status:

Field	What it holds
`type`	What it holdsA link to the code’s page in this reference.
`title`	What it holdsThe code’s meaning in a short sentence, for people. Its wording can change.
`status`	What it holdsThe HTTP status, repeated in the body.
`code`	What it holdsThe stable name to branch on. It never changes its meaning.
`request_id`	What it holdsOur ID for this request. Quote it when you contact us.
`detail`	What it holdsSometimes: more about this occurrence, for people.
`errors`	What it holdsWith validation_failed: each wrong field’s path, code and message.
`retry_after`	What it holdsWith some 429 and 503 answers: how many seconds to wait first.

How errors work in the API guide

An error answer

JSON

{
  "type": "https://docs.mydeepagents.com/errors/not_found",
  "title": "The resource was not found.",
  "status": 404,
  "code": "not_found",
  "request_id": "req_01jb8m4s2v7q9x3k5n6p8r0t2w"
}

The request

Something about the request itself: its shape, its body, its headers or what it points to.

Code	Status	Title
`bad_request`	Status400	TitleThe request is malformed.
`not_found`	Status404	TitleThe resource was not found.
`method_not_allowed`	Status405	TitleThe method is not allowed on this resource.
`not_acceptable`	Status406	TitleNo acceptable representation is available.
`unsupported_media_type`	Status415	TitleThe content type is not supported.
`payload_too_large`	Status413	TitleThe request body is too large.
`validation_failed`	Status422	TitleThe request is not valid.
`idempotency_key_reuse`	Status422	TitleThe idempotency key was used with a different request.
`request_in_progress`	Status409	TitleA request with this idempotency key is in progress.
`precondition_failed`	Status412	TitleThe resource has changed since you read it.

Signing in

The credential is missing or too old, or a person’s own sign-in needs another step.

Code	Status	Title
`unauthenticated`	Status401	TitleAuthentication is required.
`token_expired`	Status401	TitleThe access token has expired.
`step_up_required`	Status401	TitleA fresh multi-factor sign-in is required.
`reauth_required`	Status401	TitleConfirm it is you first.
`invalid_credentials`	Status401	TitleThe email or password is not right.
`invalid_code`	Status401	TitleThe code is not right, or it has expired.
`account_unconfirmed`	Status401	TitleThis account's email address is not confirmed yet.
`password_reset_required`	Status401	TitleThis account needs a new password.
`signin_expired`	Status410	TitleThis sign-in has expired. Start again.
`weak_password`	Status422	TitleThe password does not meet the rules.
`passkey_unavailable`	Status422	TitleA passkey cannot be used here.
`account_exists`	Status409	TitleAn account with this email already exists.
`password_changed`	Status409	TitleThe password was changed. Sign in with it.

Access

The caller is known, but may not do this here.

Code	Status	Title
`permission_denied`	Status403	TitleYou do not have permission to do this.
`scope_insufficient`	Status403	TitleThe credential's scope does not allow this.
`policy_denied`	Status403	TitleA compliance rule does not allow this.
`ip_not_allowed`	Status403	TitleRequests from this address are not allowed.
`task_content_not_visible`	Status403	TitleYou cannot see what this task asks you to approve.
`tenant_suspended`	Status451	TitleThe tenant is suspended.
`key_unavailable`	Status423	TitleThe tenant's encryption key is unavailable.
`chat_disabled`	Status403	TitleChat is turned off for this organization.

Conflicts and state

The request is fine, but the thing it acts on is not in a state that allows it.

Code	Status	Title
`already_exists`	Status409	TitleThe resource already exists.
`alias_in_use`	Status409	TitleThe alias is in use.
`has_children`	Status409	TitleThe tenant still has child tenants.
`run_in_progress`	Status409	TitleA run is already in progress.
`task_already_decided`	Status409	TitleSomeone has already decided this task.
`export_in_progress`	Status409	TitleAn export of this organization is already running.
`stream_expired`	Status410	TitleThe stream is no longer available.
`version_archived`	Status410	TitleThe version has been archived.
`slot_unbound`	Status422	TitleA connection slot is not bound.
`publish_blocked`	Status422	TitleThe definition cannot be published.
`tool_unavailable`	Status422	TitleA chosen tool cannot be used.
`thread_full`	Status409	TitleThe conversation has reached its message limit.

AI models

The model provider, its key or the model itself could not do what was asked.

Code	Status	Title
`llm_key_invalid`	Status422	TitleThe model provider rejected the key.
`llm_key_billing`	Status422	TitleThe model provider account has a billing problem.
`model_unavailable`	Status422	TitleThe model is not available here.
`model_param_unsupported`	Status422	TitleThe model does not support this parameter.
`model_refused`	Status422	TitleThe model declined the request.
`context_overflow`	Status422	TitleThe conversation is too long for the model.
`model_retired`	Status410	TitleThe model has been retired.
`llm_busy`	Status429	TitleThe model capacity is busy.
`llm_request_invalid`	Status502	TitleThe model provider rejected the request.
`llm_unavailable`	Status503	TitleThe model provider is temporarily unavailable.
`llm_timeout`	Status504	TitleThe model provider did not answer in time.

Limits

A rate, concurrency or spending limit was reached.

Code	Status	Title
`rate_limited`	Status429	TitleToo many requests.
`concurrency_limited`	Status429	TitleToo many concurrent operations.
`budget_exceeded`	Status429	TitleThe budget has been exceeded.

Website widgets

Answers of the widget gateway, which the chat on a customer’s website talks to.

Code	Status	Title
`widget_key_invalid`	Status404	TitleThe widget key does not exist.
`widget_key_revoked`	Status403	TitleThe widget key has been revoked.
`widget_disabled`	Status403	TitleThe widget is turned off.
`origin_not_allowed`	Status403	TitleThis site may not show the widget.
`consent_required`	Status403	TitleThe visitor has not agreed to the consent text yet.
`identity_required`	Status401	TitleThe visitor must be signed in.
`identity_token_invalid`	Status401	TitleThe visitor's identity token is not valid.
`session_expired`	Status401	TitleThe chat session has expired.
`message_too_large`	Status413	TitleThe message is too long.
`spend_cap_reached`	Status429	TitleThe widget's daily spending limit is reached.
`uploads_off`	Status403	TitleThis widget does not accept files.
`upload_too_large`	Status413	TitleThe file is too large.
`upload_type_not_allowed`	Status415	TitleThis kind of file can't be attached here.
`upload_unreadable`	Status422	TitleThe file can't be used.
`voice_off`	Status403	TitleThis widget does not take voice.
`speech_empty`	Status422	TitleNo speech was heard.
`speech_unsupported`	Status422	TitleThis recording or voice can't be used.
`speech_failed`	Status502	TitleSpeech could not be processed right now.

Our side

Something on the platform failed or is briefly unavailable.

Code	Status	Title
`internal_error`	Status500	TitleSomething went wrong on our side.
`unavailable`	Status503	TitleThe service is temporarily unavailable.
`authz_unavailable`	Status503	TitleAuthorization is temporarily unavailable.

Build with us

Ready for your first call?

Early access is open. Tell us what you want your agents to do, and we will help you get your first key.

Talk to us Read the API guide