// Docs · Errors

Errors, plain English.

Two layers can return an error. The gateway itself (4xx, 5xx with structured JSON), and the underlying nginx edge (5xx HTML pages on malformed requests). Both are documented below. If an error you see is not on this page, please file it — we will list it or fix it.

// 4xx vs 5xx, in one line 4xx — your request needs fixing; retry only after fixing. 5xx — SLASHED or an upstream provider is unhealthy; retry with backoff is appropriate.

01Structured-error response shape

For 4xx and 5xx from the gateway's own logic, the response body is JSON in OpenAI-compatible error shape:

// HTTP/1.1 401 Unauthorized
// Content-Type: application/json
{
  "error": {
    "message": "Invalid API key provided.",
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "param": null
  }
}

The OpenAI SDK maps this to its APIError / AuthenticationError / RateLimitError hierarchy automatically. Existing OpenAI exception handlers work unchanged.

02Edge-layer errors (nginx HTML)

If a request never reaches the gateway's structured-error layer — bad HTTP method on a documented path, malformed URL, oversized body before any gateway parsing — the edge nginx layer returns a plain HTML response. The documented current shape, observed live:

// Observed live: GET https://api.slashed.pro/v1/chat/completions
// Returns: HTTP/1.1 405 Method Not Allowed
<html>
<head><title>405 Not Allowed</title></head>
<body>
<center><h1>405 Not Allowed</h1></center>
<hr><center>nginx/1.29.8</center>
</body>
</html>

If you receive HTML where you expected JSON, you have hit the edge layer. The most common cause is using the wrong HTTP method (e.g. GET /v1/chat/completions instead of POST). Re-issue with the documented method — see /docs/endpoints.

03Reference table — 4xx

Status	What it means	Retry?
400 invalid_request	Request body or query parameter is malformed. Common causes: missing `model`, missing `messages`, bad JSON, schema mismatch on `tools`. The `error.message` field names the offending field where possible.	no — fix first
401 invalid_api_key	Missing, malformed, or unknown `Authorization` header. The key may have been revoked. Verify with /docs/authentication step 5 and rotate if exposed.	no — fix first
402 monthly_cap_exceeded	This key has hit its monthly spend ceiling. Lift the ceiling in the dashboard or wait for the next billing cycle. Other keys on the same account are not affected.	no — fix first
403 model_not_allowed	The key's `model allowlist` does not include the requested `model` ID. Either expand the allowlist in the dashboard, or pick a permitted ID from /docs/models.	no — fix first
404 not_found	Path is not documented. Notably: `/v1/embeddings`, `/v1/completions`, `/v1/files`, `/v1/audio`, `/v1/images` are not documented today and will 404. See /docs/endpoints §07.	no — wrong path
405 method_not_allowed	HTTP method does not match the endpoint contract. `/v1/chat/completions` is POST-only. `/v1/models` is GET-only. Response is the edge nginx HTML page, not JSON.	no — fix method
413 payload_too_large	Request body exceeds the documented size limit. Most often hit by oversized base64 image data. Trim, or supply images via remote URL.	no — fix size
429 rate_limit_exceeded	Documented as forwarded from upstream rate-limit signal. The gateway does not currently document a per-key rate-limit envelope of its own. If the upstream returns 429, the gateway returns 429. Back off and retry per upstream's recommended cadence.	yes — with backoff

04Reference table — 5xx

Status	What it means	Retry?
500 internal_error	Unhandled gateway condition. Often means an upstream provider returned a malformed response or the gateway hit an unexpected internal state. The request may have partially succeeded — check the dashboard ledger before retrying.	maybe — check ledger
502 bad_gateway	Upstream provider returned an invalid response. Documented as transient. Retry with exponential backoff.	yes — backoff
503 service_unavailable	Gateway or specific upstream model temporarily over capacity. Documented as transient. Check status.slashed.pro for incidents.	yes — backoff
504 upstream_timeout	Upstream provider did not respond within the gateway timeout window. Common with very-long completions or cold-start latency. Re-issue or lower `max_tokens`.	yes — backoff

05Documented retry pattern

For retryable codes (429 / 502 / 503 / 504), the documented backoff cadence is exponential with jitter, up to 4 retries:

1st retry: 500 ms ± 250 ms
2nd retry: 1.5 s ± 500 ms
3rd retry: 4 s ± 1 s
4th retry: 10 s ± 2 s

The OpenAI SDK applies a similar default. If you let the SDK retry, do not also retry at your application layer — doubling backoff is wasted budget.

06Differences from Quatarly

If you are migrating from Quatarly, you may have seen these patterns. SLASHED differs in three ways — the rest are documented as identical or near-identical:

Auth header. SLASHED uses Authorization: Bearer sl-..., the OpenAI-spec shape. Quatarly's X-Quatarly-Token header is not accepted — passing it returns 401 invalid_api_key.
Key prefix. SLASHED keys are sl-.... Quatarly keys (qua-...) will not authenticate.
Error envelope. SLASHED returns OpenAI-spec {"error": {"message", "type", "code", "param"}}. Quatarly's older envelope ({"err_code", "err_msg"}) is not emitted by SLASHED — if your code parses Quatarly's shape, switch to the OpenAI shape.

See /docs/migrate for the full migration step list.

// On "documented" vs "guaranteed" The behaviour described on this page is what SLASHED documents today. The gateway proxies upstream provider semantics — if an upstream provider changes its error envelope, the gateway will reflect that. Retry-after headers, when present, are forwarded but not synthesized.

← Previous

Endpoints

Migrate from Quatarly