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). 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.
{
"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.