Error codes

Every error code the API returns, by status, and when to retry.

Every code the API returns, by HTTP status, from the spec each endpoint is tested against. Errors covers handling them.

The error shape

JSON
{
  "error": {
    "message": "Incorrect API key provided.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}
error.messagestringRequired

A sentence that says what went wrong and what to do. It's for people, and it can change.

error.typestringRequired

The error's family, such as invalid_request_error, insufficient_balance, quota, requests, upstream_error, or server_error.

error.paramstring | nullRequired

The setting at fault, such as key.min_privacy, when there is one. Otherwise null.

error.codestringRequired

The specific error. It's stable, so branch on it.

A path the API doesn't serve returns 404, and a wrong method 405, both as plain text. During a stream, an error arrives as the last event: see Streaming format.

Debugging a request

  • Read message. It names the field or the limit at fault.
  • Quote X-Request-Id when you write to support. An error that arrives after the request starts carries it too.
  • Check the key's settings in the console: its allowed IPs, its spend limit, its expiry, its privacy floor, and whether it lets settings reach the model host.

When to retry

StatusRetry
400Never unchanged. Fix the request.
401Never unchanged. Fix the key.
402After adding credits, or after the key's limit resets, as Retry-After says.
403Never unchanged. The key or account can't make the request.
404Never unchanged. Fix the model's id.
408Yes, sending the body faster.
413Never unchanged. Send a smaller body.
422Not for the same page.
429After the seconds in Retry-After.
502After a short wait, or with another model.
503After the seconds in Retry-After, or shortly.

400 Bad request

CodeWhen
content_filterThe model provider declined the request.Chat completionsThe provider declined the prompt.Images
context_length_exceededThe conversation is too long for the model.Chat completions
duplicate_json_keyA JSON object in the body repeats a key.Chat completions, Images, Search, Fetch
e2ee_field_refusedAn E2EE request carries a field or value outside the e2ee client contract, such as tools on a model sealed to Phala, or provider.min_privacy, which every e2ee model already meets. Morse forwards the encrypted body as sent and cannot remove it. The message names the field.Chat completions
e2ee_output_limit_refusedAn E2EE request sets max_tokens or max_completion_tokens above the e2ee tier's max_output_tokens, or sets both to different values. Morse forwards the encrypted body as sent and cannot lower them.Chat completions
e2ee_output_limit_requiredAn E2EE request sets neither max_tokens nor max_completion_tokens, or sets both to null. Morse forwards the encrypted body as sent and cannot add a limit.Chat completions
e2ee_unsupported_modelThe request carries end-to-end encryption headers, which no transcription model takes. An incomplete set gets the e2ee_ code that names what is wrong with it instead.Transcriptions
invalid_output_limitmax_tokens or max_completion_tokens is not a positive integer.Chat completions
invalid_parameterA field has a value the endpoint refuses. The message names the field.Chat completions, Images, Search, Fetchshape is any value but tiers or aliases, or is sent more than once. The message names tiers and aliases.Modelsqueries, a query, or objective is out of range. The message names it.SearchThe body is not a multipart form with a model and a file, a field is unknown or sent twice, the file is not a WAV file of 16-bit PCM, mono or stereo, at 8 to 48 kHz, or holds no audio, language is not a code Whisper transcribes, or response_format is not json. The message names the problem.Transcriptions
invalid_requestA message, part, or tool has a shape the model does not take, or the provider refused the request.Chat completionsThe provider rejected the request.ImagesThe provider could not read the audio.Transcriptions
invalid_request_bodyThe body is not a JSON object, a field has the wrong JSON type, or model is missing.Chat completions, Images, Search, Fetch
invalid_urlurl is missing, or not an http or https URL of at most 2,048 characters on a public host and the default port.Fetch
max_price_unmetEvery tier of the model costs you more than provider.max_price allows, at your price: list for an API key. The message names the cheapest tier's price.Chat completions
message_too_longIn a chat with a character, the last user message holds more than 8,000 bytes of text.Chat completions
model_unsupported_for_charactersA chat that plays a character, one that sends X-Character or a character's prompt, names a model that GET /v1/models lists with characters false. param is model. Morse refuses before it calls the model or holds any credit.Chat completions
privacy_floor_unmetThe model's tier is below provider.min_privacy, or below the API key's min_privacy, when param is key.min_privacy, or no endpoint at the tiers the request may run at keeps no data when the request sets provider.zdr or provider.data_collection deny. The message names both tiers. GET /v1/models lists only the models the key may call. Morse refuses before it calls the model or holds any credit.Chat completionsThe model's tier is below the API key's min_privacy. param is key.min_privacy, and the message names both tiers. GET /v1/models lists only the models the key may call. Morse refuses before it calls the model or holds any credit.Images, Search, Fetch, Transcriptions
provider_choice_unsupportedprovider names only, ignore, or enforce_distillable_text. Morse chooses the provider within a privacy tier and refuses a request that would ignore the choice. The message points to the Pricing page, which lists the providers, and to provider.min_privacy, which requires a tier.Chat completions
quantization_unmetNo host of the model at the tiers the request may run at serves a precision that provider.quantizations admits. param is provider.quantizations, and the message names the precisions those hosts do serve. Morse never moves a request to another tier to find one, so a precision that only a tee host serves needs min_privacy tee. Morse refuses before it calls the model or holds any credit.Chat completions
quantization_unsupportedAn E2EE request sealed to a Phala or NEAR endpoint names provider.quantizations. A body sealed to Phala must carry provider exactly {"aci_verified":true,"zdr":true}, and a body sealed to NEAR is forwarded verbatim and may carry no provider field, so neither route can take quantizations. param is provider.quantizations, and the message names the model and the vendor. Morse refuses before the vendor's body check, before it calls the model or holds any credit.Chat completions
remote_mediaA media part links a URL instead of a data: URL.Chat completionsA reference image links a URL instead of a data: URL.Images
request_too_complexThe body holds more than 262,144 JSON values.Chat completions
setting_not_forwardedAn API key whose forward_settings was turned off set temperature, top_p, stop, seed, n, or a response_format other than {"type":"text"}, which Morse sends to no model for it. A new key has forward_settings on unless it is created with forward_settings false or null. The message names the field and the key setting, "Let my settings reach the model host", that sends them, and the developer console's keys page, https://console.trymorse.ai/keys, where it is turned back on.Chat completions
too_many_messagesmessages holds more than 4,096 entries.Chat completions
unsealable_requestA plaintext request to an e2ee model carries a field Morse cannot seal for you, such as tools, and no other endpoint of the model at the tiers the request may run at takes it. Send only system, user, and assistant messages with string content, or seal the request yourself. The message names the field.Chat completions
unsupported_inputAn API key's messages carry an image part for a model whose input_modalities in GET /v1/models do not include image. The message names what the model reads. Morse refuses before it calls the model or holds any credit.Chat completions
unsupported_parameterprovider.max_price names image, audio, or request, which no chat price has; the request sets a field that changes the reply and that Morse sends to no model, such as logprobs or frequency_penalty; or an API key whose forward_settings is on sets temperature, top_p, stop, seed, n, or response_format on a model none of whose hosts Morse sends them, such as a Claude model, or a response_format of type json_object or json_schema that no endpoint of the model honours, when the message names the type; or an API key's request lets a model that GET /v1/models lists with tools false call a tool, with tools or a tool_choice other than none, when the field named is tools. The message names the field.Chat completions

401 Unauthorized

CodeWhen
api_key_expiredThe key is past the expiry set on it. Make a new key, or set a later expiry before a key expires.Every endpoint
invalid_api_keyThe Authorization header is missing or not Bearer, the key is unknown or revoked, a token that starts with sk_ is not a whole sk_morse_ key, or the bearer is no Morse key or login token at all, such as another service's API key (sk-proj-...).Every endpoint
invalid_tokenThe bearer is shaped as a Morse login token (a JWT) but its signature fails or it has expired. An API key sends the whole sk_morse_ key.Every endpoint

402 Payment required

CodeWhen
insufficient_balanceThe balance is below the amount the request must hold. While the balance is negative, the API refuses every metered request. With no credit left, a balance of zero or below, the message says only to add credit, since no lower max_tokens would help.Chat completionsThe balance is below the amount the request must hold. While the balance is negative, the API refuses every metered request.Images, Search, Fetch, Transcriptions
key_spend_limit_reachedWhat the key's spend limit has left in its window is below the amount the request must hold. A limit that resets daily, weekly, or monthly sends Retry-After, the seconds until it resets. A limit that never resets sends none. Raise or remove the limit in the dashboard, and the next request is served.Chat completions, Images, Search, Fetch, Transcriptions

403 Forbidden

CodeWhen
account_deletedThe key's account has been deleted.Every endpoint
account_disabledMorse has disabled the key's account.Every endpoint
account_under_18The account's owner said they are under 18.Every endpoint
characters_app_onlyThe first system message opens with the prompt of a Morse character, or the request names one in X-Character-Content or sends X-Writer-Examples. Morse characters are available only in the Morse app, not through an API key.Chat completions
ip_not_allowedThe key allows requests only from its allowed IPs, and the request came from another address. The message names the address the proxy saw.Every endpoint
sealed_requiredThe key is sealed_only, and the request came unsealed. Send it inside POST /v1/sealed, as the Morse app does.Chat completions, Images, Search, Fetch, Transcriptions

404 Not found

CodeWhen
model_not_foundNo model of this endpoint's type has that name.Chat completions, Images, Search, Fetch, TranscriptionsThe id names no model or alias that GET /v1/models lists to this caller, such as a model below the key's min_privacy or one only the Morse app may use.Model

408 Request timeout

CodeWhen
request_timeoutThe request body did not arrive within one minute.Chat completions, Images, Search, Fetch, Transcriptions

413 Payload too large

CodeWhen
request_too_largeThe body is over 32 MiB, or too large for the provider.Chat completions, ImagesThe body is over 64 KiB.Search, FetchThe body is over 10 MiB, or the recording is longer than 5 minutes.Transcriptions

422 Unprocessable

CodeWhen
fetch_failedThe provider returned no content for the page.Fetch

429 Too many requests

CodeWhen
concurrency_limit_exceededThe account already has its maximum number of requests in flight. Retry-After is 1.Chat completions, Images, Search, Fetch, Transcriptions
rate_limit_exceededThe account used up its requests per minute. All of the account's keys and its owner's use of the Morse app share one budget.Chat completions, Images, Search, Fetch, TranscriptionsThe account used up its 60 model lists a minute. All of the account's keys and its owner's use of the Morse app share them. Up to 7 lists can go at once, then one each second.Models, Model

502 Bad gateway

CodeWhen
upstream_errorThe provider failed or did not answer.Chat completions, TranscriptionsThe provider failed, returned no images, or took more than 10 minutes.ImagesThe provider failed or did not answer in time.Search, Fetch
upstream_refusedThe provider refused the request, such as when it does not serve the model to Morse right now. Retry later, or choose another model.Chat completions, Images
upstream_retentionA zero-retention model's provider did not confirm zero data retention.Chat completions
upstream_unavailableThe provider is unavailable right now. Retry later, or choose another model.Chat completions, Images, Search, FetchThe provider is unavailable right now. Retry later.Transcriptions

503 Service unavailable

CodeWhen
server_busyMorse is busy. Retry-After is 1.Chat completions, Images, Search, Fetch, Transcriptions
service_unavailableMorse could not start the request. Retry it.Every endpoint
upstream_busyThe provider is overloaded. Try again shortly.Chat completions, ImagesThe web provider is busy for every Morse account. Retry-After says when to retry.Search, FetchThe transcription provider is busy for every Morse account, or busy itself. Retry later.Transcriptions
upstream_unattestedMorse could not verify the attested endpoint. Try again shortly.Chat completions, Transcriptions