Browse the documentation

REST API

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). Calls that fail do not count. The quota resets on your billing anniversary.

Every response carries the quota headers:

HeaderMeaning
X-RateLimit-LimitCalls allowed in the current cycle
X-RateLimit-RemainingCalls left
X-RateLimit-ResetEnd 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

StatusMeaning
200, 201Success
204Success, nothing to return (a model without a FINANCE.md)
207A batch partly applied: read failed
400Invalid request: the body fails validation
401Missing, invalid or expired token
403The token cannot do this (read-only key, another model's key, plan limit)
404Not found, or not visible to you
409Conflict: a concurrent write changed the model, or a deletion would break dependents
422A batch applied nothing
429Rate limit or quota reached
500Server 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"]
}
CodeStatusExtra fields
VALIDATION_ERROR400details: one line per invalid field, with its path
MODEL_VALIDATION_ERROR400validation_errors: the modelling rules the write would break
INVALID_JSON400
BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, RATE_LIMITED400 to 429The default code of each status, when no more specific code applies
INTERNAL500

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.