Reference: What each status code means and what to do

400 Bad Request

The request reached us but the body can’t be parsed or a required field is missing.

Malformed JSON body; missing model field.

Read the full body to find the offending field. Check that your JSON is valid and model is present.

401 Unauthorized

The API key is missing, inactive, or not sent as a Bearer token.

Key not sent as a Bearer token; expired or inactive key; key without the flp_ prefix.

Verify you’re sending a valid flp_… key as Authorization: Bearer <key>. Regenerate it in the Suite if needed. Common gotcha: pass the variable name to getenv, not the key value itself.

403 Forbidden

The key is valid but not allowed for this request — or there’s a billing/plan problem. There is no separate 402 on our platform; payment issues come back as 403.

No active plan, expired plan, or credits exhausted; no default payment method; wrong endpoint ID on a Dedicated endpoint; the key’s default team isn’t the funded team.

Check your team role and that the key’s default team matches where your endpoint and credits live, or pass X-Friendli-Team in the header of your request. Add or verify a card and clear invoices under Team Settings → Billing. For Dedicated, verify the endpoint ID is correct.

404 Not Found

The requested resource doesn’t exist for this request.

Wrong or mistyped endpoint_id/model; deleted, terminated, or sleeping endpoint; wrong base URL (serverless vs. dedicated); a deprecated serverless model — this 404 is expected, not an outage.

Double-check the ID and base URL, confirm the deployment exists, and wake or restart a sleeping endpoint. If the model was deprecated, migrate to another model or a Dedicated Endpoint. Check friendli.ai/docs/changelog for deprecation schedules.

422 Unprocessable Entity

The request is well-formed but has invalid parameters or values. We validate requests, including tool schemas, rather than ignoring unsupported fields.

Unknown fields; tool schema issues (oneOf, dangling $ref); tools + response_format / min_tokens combinations; parameter out of range; context length exceeded; top_logprobs on reasoning models.

See the full breakdown in I’m getting HTTP 422 “Unprocessable Entity.” What does it mean?

429 Too Many Requests

Rate limited — either your tier’s RPM cap or shared-capacity contention on Model API.

Tier limit reached, or a demand spike on a shared/high-demand model, which can happen even below your RPM.

Add retry with backoff and lower concurrency; use a fallback model; raise your tier; or move to a Dedicated Endpoint for guaranteed capacity.

500 Internal Server Error

A server-side failure while processing the request. Retryable.

Transient fault; endpoint-creation call missing required config; restart/wake on a terminated endpoint.

Retry after a short delay. If it persists, send our Support team the request details and timestamps.

503 Service Unavailable

The service is overloaded or an endpoint’s queue timed out; occasionally an infrastructure incident.

Very large token sizes causing queue timeouts; a temporary capacity or infra issue.

Reduce input size and/or max_tokens, then retry. For a broad outage, we’ll investigate and share an update.

Timeouts / hangs

The request stalls or never returns.

Forcing tool_choice on some models (GLM-5.2 in particular); very long outputs; a deployment still acquiring GPUs (“stuck at 1%”).

Avoid forcing a tool call where it may not fit; reduce output length; for deploys, allow time for GPU allocation. Share timestamps if it persists.