Conventions
Errors
Error response shape, status codes, and recovery guidance
Every error response is JSON with at least an error string. Additional fields
(reason, retryAfter) may be present depending on the failure.
Envelope
{
"error": "Subscription is no longer active",
"reason": "subscription_expired"
}| Field | Type | Description |
|---|---|---|
error | string | Human-readable message. Safe to log; not safe to render verbatim to end users without context. |
reason | string | Machine-readable enum for branching logic. Present on billing and access errors. |
retryAfter | number | Seconds to wait before retrying. Present on 429. |
The API does not wrap success responses in an envelope. Successful
responses are the resource (or { "success": true } for void operations).
Status codes
400Bad request — invalid payload or query params.
{ "error": "Invalid request body: 'date' is required" }401Unauthorized — missing, invalid, or expired credentials.
{ "error": "API key has expired" }402Payment required — subscription lapsed.
{ "error": "Your subscription has lapsed. Update payment to keep making changes.", "reason": "subscription_past_due" }403Forbidden — authenticated but lacking the required role or permission.
{ "error": "Insufficient permissions" }404Not found — resource does not exist or is outside your organization.
{ "error": "Event not found" }409Conflict — resource state prevents the operation (e.g. duplicate).
{ "error": "An event with this name already exists" }422Validation failed — payload shape is valid but values are not.
{ "error": "End date must be after start date" }429Rate-limited. See Rate limits.
{ "error": "Rate limit exceeded", "retryAfter": 42 }500Server error. Retry with exponential backoff. Include the request ID in support tickets.
{ "error": "Internal server error" }Recovery guidance
| Status | Retry? | Strategy |
|---|---|---|
400, 422 | No | Fix the payload before retrying. |
401 | No | Re-authenticate. If the key is expired, generate a new one. |
402 | No | Update billing in the dashboard. |
403 | No | Have an admin grant the required role/permission. |
404 | No | Verify the ID. Cross-org IDs return 404, not 403. |
409 | Sometimes | Reconcile state, then retry. |
429 | Yes | Honour retryAfter. See Rate limits. |
5xx | Yes | Exponential backoff (e.g. 1s, 2s, 4s, 8s, max 60s). |
Multi-tenancy
The API enforces organization scoping silently — a resource from another
organization returns 404, not 403. This prevents ID enumeration across
tenants.