Errors

Scenema uses conventional HTTP status codes for every response and a stable JSON error shape when the response carries a body.

Error body shape

{
  "error": "<human-readable message>",
  "code": "<optional machine-readable code>"
}

Some error responses carry additional fields relevant to the specific failure. Rate-limit responses carry retryAfterMs. Plan-gate responses carry an upgrade object with the current and required plan ids. Every additional field is optional; parsers should not fail when they are missing.

Status codes

Common code values

Where a body ships with code, it is drawn from a stable enum. The current codes:

• RATE_LIMITED. Workspace rate limit reached. Ships with 429. See Rate Limits.
• PLAN_UPGRADE_REQUIRED — feature not on your plan. Ships with 403.
• LIMIT_REACHED — feature on your plan but the per-period quota is spent. Ships with 403.
• PLAN_CAP_TRUNCATED — soft cap: your write succeeded but the payload was clipped to fit your plan. Ships with the standard success code for the endpoint; the body carries the truncation notice so you can prompt the user to upgrade if the full length matters.
• INSUFFICIENT_CREDITS — workspace credit balance cannot cover the operation. Ships with 402. Body carries the full balance and upgrade options.

Idempotency and retries

Read requests are always safe to retry. Mutation requests are idempotent at the resource level:

• Creating the same resource twice yields two distinct rows.
• Revoking or disabling something already gone or already disabled returns the terminal success code (404 or 204) without side effects.
• Toggling enabled to the state it already holds is a no-op.

Retry policy that works across every endpoint:

1. On 429, honor Retry-After. Do not use your own backoff schedule.
2. On 5xx, use exponential backoff starting at 500ms with a cap at 30s and a request-level max of five attempts.
3. On 4xx other than 429, do not retry. Fix the request or surface the error to the operator.

Debugging authentication failures

401 is the single most common error to encounter during setup. In order of likelihood:

1. Missing Bearer prefix on the header. The correct form is Authorization: Bearer sk_.... Sending Authorization: sk_... returns 401.
2. Wrong header name. Scenema uses Authorization, not X-API-Key or Api-Key.
3. Trailing whitespace or newline on the key. Common when copy-pasting; the extra character makes the hash lookup fail.
4. Expired key. Check the row in the Settings tab for the expiry.
5. Disabled key. Check the row’s enabled toggle.
6. Revoked key. No row in the list means the key was revoked; mint a new one.