# Limits and errors

> Rate limits, the monthly API quota and its headers, HTTP status codes, the error body and the error codes returned by the Layerz REST API.

## Limits

Two limits apply independently:

- **Burst**: 120 requests per minute per IP address.
- **Monthly quota**: each successful call counts one toward your plan's monthly allowance (see [Pricing](/pricing)). Calls that fail do not count. The quota resets on your billing anniversary.

Every response carries the quota headers:

| Header                  | Meaning                            |
| ----------------------- | ---------------------------------- |
| `X-RateLimit-Limit`     | Calls allowed in the current cycle |
| `X-RateLimit-Remaining` | Calls left                         |
| `X-RateLimit-Reset`     | End of the cycle, in epoch seconds |

Over either limit, the API answers `429`. Past the monthly quota the code is `QUOTA_EXCEEDED`, with the reset date in `resets_at` and the plans page in `upgrade_url`.

## Status codes

| Status       | Meaning                                                                              |
| ------------ | ------------------------------------------------------------------------------------ |
| `200`, `201` | Success                                                                              |
| `204`        | Success, nothing to return (a model without a FINANCE.md)                            |
| `207`        | A batch partly applied: read `failed`                                                |
| `400`        | Invalid request: the body fails validation                                           |
| `401`        | Missing, invalid or expired token                                                    |
| `403`        | The token cannot do this (read-only key, another model's key, plan limit)            |
| `404`        | Not found, or not visible to you                                                     |
| `409`        | Conflict: a concurrent write changed the model, or a deletion would break dependents |
| `422`        | A batch applied nothing                                                              |
| `429`        | Rate limit or quota reached                                                          |
| `500`        | Server error, reported to our monitoring                                             |

## Error body

Every error carries a human-readable `error` and a machine-readable `code`; read the code, never the prose.

```json
{
  "error": "Validation error",
  "code": "VALIDATION_ERROR",
  "details": ["items.0.role: Invalid option"]
}
```

| Code                                                                                | Status     | Extra fields                                                        |
| ----------------------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------- |
| `VALIDATION_ERROR`                                                                  | 400        | `details`: one line per invalid field, with its path                |
| `MODEL_VALIDATION_ERROR`                                                            | 400        | `validation_errors`: the modelling rules the write would break      |
| `INVALID_JSON`                                                                      | 400        |                                                                     |
| `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `CONFLICT`, `RATE_LIMITED` | 400 to 429 | The default code of each status, when no more specific code applies |
| `INTERNAL`                                                                          | 500        |                                                                     |

A `MODEL_VALIDATION_ERROR` lists each broken rule with its own code, for example `UNKNOWN_UID` (a reference to nothing), `CIRCULAR_DEPENDENCY` (a formula reading itself in the same period), `FORMULA_EXPR_AND_CHILDREN` (a formula with both an expression and children), `INVALID_ROLE_CHILD` (a child the parent cannot hold), `UNKNOWN_FORMAT` (a number format neither built in nor declared). A deletion that would leave formulas pointing at nothing returns `409` with `DEPENDENCY_BLOCK`.

## Retrying

A `409` after a concurrent write is safe to retry on fresh data. A request that timed out may have applied: read the model (or its history) before sending creations again, since a repeated create makes new items.
