> For the complete documentation index, see [llms.txt](https://docs.meganova.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.meganova.ai/api-reference/platform-api/errors.md).

# Errors & Response Conventions

How MegaNova APIs report success and failure, status codes you should expect, and behavior during deploys.

MegaNova has two response shapes across three API surfaces. Know which one you're calling so your client handles each correctly.

## Surface 1 — Platform API (`https://api.meganova.ai/api/v1/...`)

Used for account, billing, API-key, usage, and tier management.

### Success

```json
{
  "data":    { /* endpoint-specific payload */ },
  "message": "Human-readable success message",
  "status":  "success"
}
```

`data` can be an object, a list, or `null` depending on the endpoint. Paginated endpoints include pagination metadata either alongside `data` or inside it — see each endpoint's doc.

### Failure

Platform endpoints typically return a non-2xx HTTP status with a JSON body describing the problem. The exact shape varies by endpoint but generally looks like:

```json
{
  "detail": "Human-readable error message"
}
```

or, for validation errors, FastAPI's standard body:

```json
{
  "detail": [
    {
      "loc": ["body", "field_name"],
      "msg": "validation message",
      "type": "value_error"
    }
  ]
}
```

## Surface 2 — Inference API (`https://api.meganova.ai/v1/...`)

OpenAI-compatible. Success responses match OpenAI's shape exactly (chat completions, completions, embeddings, images, videos, audio). Errors follow the OpenAI error envelope:

```json
{
  "error": {
    "message": "Authentication error: invalid API token passed...",
    "type": "token_not_found",
    "param": "key",
    "code": "401"
  }
}
```

Clients built on the OpenAI SDK surface these as typed exceptions automatically.

## Surface 3 — Enterprise Endpoint (`https://enterprise.api.meganova.ai/v1/...`)

The same models served from dedicated enterprise deployments. Response and error shapes are identical to Surface 2 — it is the same OpenAI-compatible API on a different base URL — with two errors specific to this surface:

| Status | `type`                  | Meaning                                                                                                                                                                                          |
| ------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `404`  | `model_not_found`       | The model has no enterprise deployment. The request is never silently served from the shared pool instead; call `GET /v1/models` on this endpoint to list what it serves.                        |
| `403`  | `libra_os_key_required` | A [Token Plan](/enterprise/token-plan.md)-covered model was called with a key that is not a plan key. Deliberate: it stops covered usage from billing your wallet instead of the plan allowance. |

See [Enterprise Endpoint](/enterprise/enterprise-endpoint.md).

## HTTP status codes

| Status | When you'll see it                                                                                                                 |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `200`  | Successful request                                                                                                                 |
| `400`  | Malformed request (bad JSON, schema validation failed)                                                                             |
| `401`  | Missing or invalid API key / JWT                                                                                                   |
| `402`  | Insufficient credits — paid model call with no balance and paid-fallback disabled                                                  |
| `403`  | Key is valid but lacks access to the requested model/resource (tier gating)                                                        |
| `404`  | Model or resource not found                                                                                                        |
| `409`  | Duplicate request, conflict on resource state                                                                                      |
| `413`  | Payload too large (e.g. oversized image)                                                                                           |
| `422`  | Request body failed validation                                                                                                     |
| `429`  | Rate limit hit — either RPM, TPM, or per-model RPD (see [Get Model Limits](/api-reference/platform-api/usage/get-model-limits.md)) |
| `500`  | Server error — retry with backoff                                                                                                  |
| `503`  | **Platform is draining for deploy** — retry the request after a brief wait; see below                                              |
| `504`  | Upstream timeout (often long-running video generations — use the async polling endpoints)                                          |

## Rate-limit behavior

Rate limiting is enforced per API key across three axes:

* **RPM** — Requests-per-minute, tier-wide (60 / 300 / 600 / 1500 for Tiers 1–4)
* **TPM** — Tokens-per-minute, tier-wide (200k / 1M / 2M / 4M for Tiers 1–4)
* **RPD** — Requests-per-day, per model (see [Free Model Quota](/free-model-quota.md) and [Model Limits](/api-reference/platform-api/usage/get-model-limits.md))

A `429` response means one of these three is exceeded. Back off and retry; the next-minute window resets RPM/TPM, and RPD resets daily at 19:00 EST.

## Graceful shutdown (`503` during deploys)

During a deploy, the backend enters a "drain" mode where new requests receive `503` responses while in-flight streaming completions are allowed to finish. This is normal and short-lived (typically seconds). Treat `503` as a transient error and retry.

If you're running a production integration, implement exponential backoff for `503` and `429`.

## Related

* [Authentication](/api-reference/platform-api/authentication.md) — How to send credentials
* [Get Model Limits](/api-reference/platform-api/usage/get-model-limits.md) — Your current RPM/TPM/RPD caps
* [Get Usage Records](/api-reference/platform-api/usage/get-usage-records.md) — Inspect per-request usage and spend