DocsOpen Moon AI
Browse the docs

Errors

The API error format, which follows OpenAI’s, the full list of codes with their status and what to do about each, and how to read errors with the SDKs.

On this page

API errors follow the OpenAI API format: the OpenAI SDKs read them with no extra setup. Every error has an HTTP status, a type, a stable code to test in your code, and a message in English meant for developers.

FormatLink to the Format section

Example: insufficient balance
{
  "error": {
    "message": "insufficient credits",
    "type": "insufficient_quota",
    "code": "insufficient_credits",
    "param": null,
    "required_credits": 5200,
    "balance_credits": 310
  }
}
FieldTypeDescription
messagestringA readable explanation, in English. Don’t test it in your code: it can change.
typestringThe error family (see below).
codestring or nullA precise, stable code. null for a few errors without a dedicated code (unreadable JSON body, malformed parameter).
paramstring or nullThe parameter at fault, when there is one (model, messages, input…).
other fieldsSome errors add details: required_credits, balance_credits, window, scope, held_credits, cap_credits, spent_credits.

type values:

typeStatusesMeaning
invalid_request_error400, 404, 405, 409, 410, 411, 413, 422The request needs fixing.
authentication_error401, 403Key missing, refused, or used outside its rules.
permission_error403Your organization’s rules refuse the request.
insufficient_quota402Balance or spend cap.
rate_limit_error429Too many requests for now: retry.
server_error500, 502, 503, 504An outage on our side or the model’s: retry.

When an error carries a Retry-After header, wait that many seconds before retrying. An error returned by the chat model also carries the request’s X-Moon-Request-Id header.

Read an error with an SDKLink to the Read an error with an SDK section

Python
import os
import openai
from openai import OpenAI

client = OpenAI(base_url="https://api.realmoon.ai/v1", api_key=os.environ["MOONAI_API_KEY"])

try:
    client.chat.completions.create(
        model="anthropic/claude-haiku-4.5",
        messages=[{"role": "user", "content": "Hello"}],
    )
except openai.APIStatusError as e:
    print(e.status_code, e.type, e.code, e.param)
    print(e.body)  # the "error" object, with its extra fields
    print(e.response.headers.get("retry-after"))
    if e.code == "insufficient_credits":
        print("Top up the workspace:", e.body.get("required_credits"), "credits needed")
except openai.APIConnectionError:
    print("Could not reach the server.")
JavaScript
import OpenAI from 'openai';

const client = new OpenAI({ baseURL: 'https://api.realmoon.ai/v1', apiKey: process.env.MOONAI_API_KEY });

try {
  await client.chat.completions.create({
    model: 'anthropic/claude-haiku-4.5',
    messages: [{ role: 'user', content: 'Hello' }],
  });
} catch (err) {
  if (err instanceof OpenAI.APIError) {
    console.log(err.status, err.type, err.code, err.param);
    console.log(err.error); // the "error" object, with its extra fields
    if (err.code === 'insufficient_credits') {
      console.log('Top up the workspace:', err.error?.required_credits, 'credits needed');
    }
  } else {
    throw err;
  }
}
cURL
curl -i https://api.realmoon.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-moon-wrong-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "anthropic/claude-haiku-4.5", "messages": [{"role": "user", "content": "Hello"}]}'

Key and accessLink to the Key and access section

These errors can happen on any endpoint.

HTTPcodeMeaningWhat to do
401invalid_api_keyKey missing, unknown, revoked or expired, workspace deleted, or workspace owner suspended.Check the Authorization: Bearer sk-moon-... header and the key’s status in the “API keys” tab.
403ip_not_allowedThe calling address is not in the key’s IP allowlist.Add the address to a new key, or call from an allowed server.
403missing_scopeThe key does not have the inference scope.Create a key from the portal.
403org_policyYour organization’s rules refuse the API or this model (type: permission_error).Choose an allowed model, or check with the organization’s administrator.
404nullnot found: the API is not enabled for this workspace.Contact support.
429rate_limit_exceededMore than 600 requests per minute with this key, too many refused requests with this key, or too many authentication failures from this address.Wait for Retry-After. See Limits.
503service_unavailableAuthentication is temporarily unavailable.Retry after Retry-After (5 seconds).
503org_policy_unavailableYour organization’s rules are temporarily unreadable.Try again in a moment.

RequestLink to the Request section

HTTPcodeMeaningWhat to do
400nullinvalid JSON body, body must be a JSON object, invalid base64, unreadable multipart form, or a malformed value (param names it).Fix the request body.
400missing_required_parameterA required parameter is missing; param names it.Add it.
400invalid_value, invalid_requestA URL parameter of the wrong type (for example limit=abc), or a malformed request.Fix the value.
400unknown_parameterA parameter unknown to a media endpoint.Remove it.
400unsupported_parameterA parameter rejected by the API or by the model; param names it when possible.Remove it or change its value.
400unsupported_valueA value outside what the model accepts (size, duration, format…).See the endpoint’s page.
400unsupported_contentMessage content not accepted (unknown part type, file by ID, video…).See Messages.
400n_not_supportedn is not 1.Send one request per response you want.
400string_above_max_lengthText longer than the endpoint’s limit.Shorten it.
404unknown_urlInvalid URL (POST /v1/...): this endpoint does not exist.Check the path; the list is in the overview.
405method_not_allowedAn HTTP method this path does not support.Use the documented method.
411length_requiredMultipart upload without a Content-Length header.Let your client compute the size (no chunked upload).
413request_too_large, file_too_largeBody or file too large.See the sizes in Limits.

ModelLink to the Model section

HTTPcodeMeaningWhat to do
404model_not_foundThe model does not exist, is not public, or does not serve this endpoint.Read GET /v1/models (with ?type= for media).
400 or 413context_length_exceededThe request is too long for the model’s context window (param: "messages").Shorten the messages or lower max_tokens.
400 or 413no_available_routeThe model cannot serve this request as is (tool, format or size not supported).Switch models or simplify the request.
400 or 413invalid_requestThe model rejected the request, with an explanation.Fix the request based on the message.
400invalid_request_errorA media model rejected the request without further detail.Change the parameters or the model.
400content_policy_violationThe model’s safety system rejected the requested content (images, videos).Rephrase the request.
503pricing_unavailableThe model’s price is temporarily unknown: the request is refused rather than billed incorrectly.Try again a little later.

Model refusals (400, 413, 429) are passed on without the provider’s name, links or internal IDs.

Credits and capsLink to the Credits and caps section

HTTPcodeMeaningWhat to do
402insufficient_creditsThe balance does not cover the request’s hold, or it is negative. required_credits and balance_credits give the amounts.Top up the workspace, or shrink the hold with max_tokens. See Costs.
402spend_cap_exceededA spend cap has been reached. scope is workspace or key, window is hour, day or month.Wait for the window to slide, or raise the cap.
402hold_exceeds_capThe hold of this single request exceeds what the cap leaves. Details: required_credits, cap_credits, spent_credits, scope, window.Lower max_tokens, or raise the cap.
429credits_held_in_progressThe balance or the cap would be enough, but in-flight requests are holding the rest (held_credits).Retry after Retry-After (2 seconds); set max_tokens when many requests run at the same time.
503billing_unavailableThe balance could not be read or charged.Try again later.

Too many requestsLink to the Too many requests section

HTTPcodeMeaningWhat to do
429rate_limit_exceededThe key’s rate limit, see Key and access.Wait for Retry-After.
429model_rate_limitedThe chat model is getting too many requests right now. Nothing is charged.Wait for Retry-After, or switch models.
429too_many_concurrentToo many media requests in flight for this workspace.Wait for a request to finish (Retry-After: 5 seconds, 30 for videos).
429upstream_rate_limitedThe media model is overloaded.Wait for Retry-After (10 seconds).

Moon BlurLink to the Moon Blur section

HTTPcodeMeaningWhat to do
413moon_blur_payload_too_largeA text exceeds 500,000 characters, too long to be scanned (param: "messages"). Nothing is sent or charged.Split the text, or turn off Moon Blur on the key.
503moon_blur_unavailablePersonal data protection could not be applied: the request is not sent to the model and nothing is charged.Retry after Retry-After (5 seconds).

See Privacy.

Model outages and serviceLink to the Model outages and service section

HTTPcodeMeaningWhat to do
502 (or another 5xx)upstream_errorThe model failed, returned an unreadable response, or could not be reached.Retry, or switch models.
503upstream_unavailable or nullThe model or the media service is temporarily unreachable.Try again later.
504upstream_timeoutThe model did not respond in time. For chat, the hold is kept (see Settlement).Retry with a shorter request, or with streaming.

Errors during a streamLink to the Errors during a stream section

Once the stream has started, the HTTP status has already been sent (200). A cut on the model side arrives as a final event:

Last event of an interrupted stream
{"error": {"message": "upstream stream interrupted", "type": "server_error", "code": "upstream_error"}}

The SDKs raise it as an error during iteration. See Streaming.

Code indexLink to the Code index section

codeHTTPEndpointsPage
audio_too_long400TranscriptionAudio
billing_unavailable503All billed endpointsCredits and caps
content_policy_violation400Images, videosModel
context_length_exceeded400, 413ChatChat completions
credits_held_in_progress429All billed endpointsCredits and caps
encrypted_document400OCROCR
file_too_large413Images, videos, transcription, OCRRequest
hold_exceeds_cap402All billed endpointsCredits and caps
insufficient_credits402All billed endpointsCredits and caps
invalid_api_key401AllKey and access
invalid_content_type400TranscriptionAudio
invalid_document400OCROCR
invalid_image400Images, videos, OCRImages
invalid_request400, 413ChatModel
invalid_request_error400MediaModel
invalid_value400AllRequest
ip_not_allowed403AllKey and access
job_not_recorded503VideosVideos
length_required411Multipart uploadsRequest
method_not_allowed405AllRequest
missing_required_parameter400AllRequest
missing_scope403AllKey and access
model_not_found404All that take a modelModel
model_rate_limited429ChatToo many requests
moon_blur_payload_too_large413Chat, embeddingsMoon Blur
moon_blur_unavailable503Chat, embeddingsMoon Blur
n_not_supported400ChatRequest
no_available_route400, 413ChatModel
ocr_busy503OCROCR
ocr_timeout504OCROCR
org_policy403All that take a modelKey and access
org_policy_unavailable503All that take a model, model listKey and access
pricing_unavailable503ChatModel
rate_limit_exceeded429AllKey and access
request_too_large413MediaRequest
service_unavailable503AllKey and access
spend_cap_exceeded402All billed endpointsCredits and caps
string_above_max_length400Images, videos, speechRequest
too_many_concurrent429MediaToo many requests
too_many_images400Image editingImages
too_many_pages400OCROCR
unknown_parameter400MediaRequest
unknown_url404AllRequest
unreadable_document422OCROCR
unsupported_content400ChatChat completions
unsupported_format400Transcription, OCRRequest
unsupported_model400Image editingImages
unsupported_parameter400AllRequest
unsupported_value400MediaRequest
upstream_error502, other 5xxAll that call a modelModel outages and service
upstream_rate_limited429MediaToo many requests
upstream_timeout504All that call a modelModel outages and service
upstream_unavailable503MediaModel outages and service
url_not_supported400OCROCR
video_expired410Video downloadVideos
video_not_found404Video status and downloadVideos
video_not_ready409Video downloadVideos

A failed video also carries an error.code in its object (generation_failed, content_policy_violation, timeout, not_found): see The video object.

Moon AI

Moon AI in action

0:00

Explore

Screenshots of chat.realmoon.ai taken on October 29, 2026, with fictional data.

Moon AI

Your preferences

Visits counted without cookies.

Our server counts visits without cookies or trackers. Your theme and your answer about ad measurement are remembered on this device.

Ad measurement

With your consent, our ad networks’ trackers (Google) measure our ads, from the visit to the sign-up and then to the first subscription and its amount, and may show you our ads. Your answer is valid for 13 months; you can change it here at any time.

No answer saved on this device.

After you decline, no tag is loaded anymore and the site deletes the cookies they had set on realmoon.ai. Those on the ad networks’ own domains are managed with them or in your browser.

The Moon AI app has its own privacy settings.