Documentation

HTTP Status Codes

Every response uses a standard HTTP status code. Apily limits each account to 600 /v1/* requests per minute across all of its API keys and answers 429 above that.

Start

Help

Python Setup

Node.js Setup

PHP Setup

API Reference

2xx Success

200 OK

Request succeeded — including the JSON error bodies below, which are 4xx/5xx, not 200.

4xx Client errors

Symptom	Cause	Fix
`400 Bad Request`	Malformed JSON body — returns a plain-HTML `<pre>Bad Request</pre>`, not JSON. On `/v1/audio/transcriptions` only, a missing `file` or `model` field returns a structured `{ error: { message, type } }` body instead.	Send valid application/json (or, for transcriptions, a complete multipart form).
`401 Missing API key`	No auth header was sent.	Apily accepts `Authorization: Bearer …` and `x-api-key: …`.
`401 Invalid API key`	Key copied with stray spaces, truncated, or revoked.	Copy the key whole from the API page in your Apily account, the `apily_` prefix included.
`403 Email not verified`	Your Apily account's email address isn't verified yet.	Verify your email from the banner in the Apily app, then retry.
`402 Insufficient balance`	Your token balance can't cover the request's estimated cost.	Top up your balance on the Billing page in your Apily account.
`404 Not found`	Path doesn't match a served route.	Base URL is `https://apily.pro/v1` — every request must land on a path Apily serves (`/chat/completions`, `/responses`, `/models`, …).
`404 Model not found`	The model ID isn't in the Apily catalog.	Copy the exact ID from `GET /v1/models` or the Models page in your account.
`429 Too many requests`	Your account sent more than 600 `/v1/*` requests in a minute — all of your API keys share one budget. The body is `{ error: { message, type: "rate_limit_error", code: "rate_limit_exceeded" }, retryAfterSeconds }`.	Wait the `Retry-After` header (or `retryAfterSeconds`) before retrying, and lower request concurrency.

5xx Server / upstream

Symptom	Cause	Fix
`500 Internal server error`	Unexpected error inside `GET /v1/models`.	Retry; report if it persists.
`502 Upstream error`	The upstream provider returned an unexpected error.	Retry the request; try a different model if it persists.
`503 Model temporarily unavailable`	The model exists, but no upstream provider is reachable right now.	Retry in a moment — it usually recovers within a minute. Switch models if it keeps happening.

Troubleshooting tips

A body starting with < is HTML, not JSON — almost always a malformed request body or the wrong path, never a normal Apily error shape.
503 Model temporarily unavailable is usually transient (no reachable provider for that model right now) — retry once before switching models.
429 Too many requests means the per-account limit (600 requests/minute) was hit — wait Retry-After seconds and lower concurrency instead of retrying immediately.