Error handling

Ship integrations that keep working when the API returns an error, hits a rate limit, or fails transiently. Meta Model API uses standard HTTP status codes and returns a descriptive error object that points to the problem.

Error response format

A failed request returns a JSON error object:

json
{
  "error": {
    "message": "`top_p`: The number must be `<= 1.0`.",
    "type": "invalid_request_error",
    "param": "top_p",
    "code": null
  }
}
FieldTypeDescription
messagestringHuman-readable detail. This is the most reliable field for diagnosis.
typestringError category: invalid_request_error for 4xx validation and not-found errors, authentication_error for 401, rate_limit_error for 429, or server_error for 5xx.
paramstring or nullRequest field that caused the error, when applicable, such as top_p or tools.
codestring or nullMachine-readable code. Frequently null on validation errors, so prefer type and message for handling. Populated for cases such as invalid_api_key, model_not_found, file_not_found, rate_limit_exceeded, server_shutting_down, service_overloaded, backend_unavailable, payload_too_large for a request body over a size limit, gateway_timeout (a non-streaming request that ran past the server-side time limit), and content_policy_violation for a media content-policy denial.
404s have no error body

A request to an unknown path returns HTTP 404 with an empty response body: there is no JSON error envelope. Detect routing mistakes from the status code directly. Only matched endpoints return the JSON shape above.

Files list returns plain-text errors

Query-string validation on the Files list endpoint (GET /v1/files) is a similar exception: an invalid order value such as ?order=sideways currently returns HTTP 400 with a plain-text body (Content-Type: text/plain), not the JSON error envelope. Branch on status code and Content-Type rather than assuming JSON on every 4xx from /v1/files.

HTTP status codes

400 Bad Request

The server could not process the request because a parameter was missing or invalid.

Common causes:

  • Missing required parameters such as model or messages
  • Invalid parameter values such as temperature outside the 0–2 range, or top_p outside 0 < top_p ≤ 1, including top_p: 0
  • max_output_tokens below the minimum of 16 on the Responses API
  • Request input plus the requested output budget exceeds the model's context window: input_tokens + max_output_tokens must fit within it (see Context window exceeded)
  • Uploading or inlining a file larger than the size limit (up to 1 GiB via the Files API, 50 MB inline)
  • Combining mutually exclusive features
  • Declaring a function tool whose name collides with a built-in tool name reserved by web_search (returns param: tools)
  • Invalid JSON in request body
  • Duplicate reasoning_id values in Responses API requests
  • Invalid conversation structure, such as a function_call_output whose call_id matches no function_call, a replayed reasoning item not followed by an assistant message or function_call, or intermediate assistant text replayed before a function_call without phase: "commentary" (see Invalid conversation structure)
  • Invalid message structure such as empty input, or unsupported role/turn combinations that violate the model's input-shape requirements
  • Submitting media (a file, image, or inline content) that does not meet Meta's content policy; returns code: content_policy_violation
  • Providing an image or media URL that cannot be fetched: for example, blocked by robots.txt, denied by fetch policy, failing DNS resolution, or otherwise unreachable. The error message identifies the specific fetch failure, for example an unreachable URL or a robots.txt denial
  • Submitting a corrupt or truncated image whose bytes cannot be decoded; the error message identifies the affected image (type: invalid_request_error, code: null)
  • Submitting an audio or video file that cannot be decoded: for example, an audio container with no audio track, a format the decoder does not recognize, or empty/corrupt media. The error message identifies the decode failure (type: invalid_request_error, code: null)

Fix: Read message and param to identify the problem. code is typically null for validation errors. Check the API reference for valid parameter combinations.

401 Unauthorized

The API key was missing, invalid, or revoked.

Common causes:

  • Missing Authorization header
  • Malformed API key (not in LLM|{id}|{secret} format)
  • Revoked or deleted API key
  • Typo in the API key
curl
curl -X POST "https://api.meta.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{"model": "muse-spark-1.3", "messages": [...]}'
json
{
  "error": {
    "message": "Unauthorized",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Both a missing key and an invalid, malformed, or revoked key return type: authentication_error with code: invalid_api_key.

Fix: Send a valid Authorization: Bearer $MODEL_API_KEY header. Verify the key in the Model API dashboard and that MODEL_API_KEY is set correctly. See Authentication for setup.

402 Payment Required

The request cannot be completed due to a billing issue.

Common causes:

  • Insufficient balance or a lapsed payment method
  • Billing account issue
json
{
  "error": {
    "message": "Billing account issue. Please check your account status.",
    "type": "billing_error",
    "param": null,
    "code": "billing_not_configured"
  }
}

Fix: Check account status and billing details in the Model API dashboard. Ensure your payment method is valid and your balance is sufficient.

403 Forbidden

The API key does not have permission to access the requested resource.

Common causes:

  • API key lacks permission for the requested model or feature