Errors, Quotas & Rate Limits

Error format

Errors are returned as RFC 9457 application/problem+json:

{
  "type": "about:blank",
  "title": "Variable validation failed",
  "status": 400,
  "code": "VALIDATION_ERROR",
  "detail": "Required variable 'discount_code' was not supplied.",
  "requestId": "req_01J9Z6Q8X..."
}

Always log requestId — it lets support trace a specific request. Branch your error handling on the numeric status and the machine-readable code.

Status codes

Code	When it happens	What to do
400	Missing required variable, or a value failed the template’s validation rules	Fix the request; the detail names the variable
401	Missing or invalid X-Api-Key	Check the header and that the key isn’t revoked
404	Template/project not found, or not accessible to this key	Verify the ID and that the template is shared/owned
429	Monthly quota or short-term rate limit exceeded	Back off and retry — see below
502	The rendering service returned an error	Retry with exponential backoff
503	The rendering service is temporarily unavailable	Retry with exponential backoff

Monthly render quota

Every workspace has a monthly render quota tied to its plan. Only image generation consumes quota — the read endpoints (list/get templates) are free.

Each generate response includes:

X-Quota-Limit: 10000
X-Quota-Remaining: 9831
X-Quota-Reset: 2026-07-01T00:00:00Z

When the quota is exhausted, generation returns 429 with:

Retry-After: 1209600          # seconds until the quota resets (start of next month)
X-RateLimit-Remaining: 0

{
  "title": "Monthly quota exceeded",
  "status": 429,
  "code": "QUOTA_EXCEEDED",
  "detail": "Monthly render quota exceeded. Quota resets at the start of next month."
}

A quota 429 will not succeed on retry until the reset time — upgrade your plan or wait. Track X-Quota-Remaining to avoid hitting the wall mid-campaign. See Usage & Quotas.

Short-term rate limit

Independent of the monthly quota, requests are throttled per second to protect the service. Exceeding the rate returns 429 with code: RATE_LIMIT_EXCEEDED and a short Retry-After (seconds):

Retry-After: 1
X-RateLimit-Remaining: 0

Distinguish the two 429 cases by the code field: RATE_LIMIT_EXCEEDED is transient (retry after a short pause), while QUOTA_EXCEEDED is not (wait for the monthly reset).

Retry guidance

• Retry 429 (RATE_LIMIT_EXCEEDED), 502, and 503 with exponential backoff (e.g. 1s, 2s, 4s, 8s), honoring Retry-After when present.
• Do not blindly retry 400, 401, 404, or 429 (QUOTA_EXCEEDED) — fix the cause instead.
• Make retried generate calls idempotent by sending a stable Idempotency-Key, so a retry returns the cached image instead of consuming quota twice. See Generating images.