API Errors and Rate Limits

Monthly quotas

API usage is metered per calendar month, based on the plan of the account that owns the API key:

• Free — 50 requests per month.
• Pro — 1,000 requests per month.

Bulk generation consumes one request per item in the batch, not per call.

Credits

If your account has purchased credits, they are used automatically once the monthly allowance is exhausted — requests keep working and are simply drawn from the credit balance instead. Every JSON response tells you which pool was used:

{ "meta": { "usage_count": 1001, "remaining": 4999, "strategy": "credits" } }

• strategy: "monthly" — the request counted against the monthly quota; remaining is what's left of it.
• strategy: "credits" — the monthly quota is used up; remaining is your credit balance.

When both the quota and credits are exhausted, requests return 429.

Status codes

• 200 — success.
• 400 — malformed JSON or a field failed validation. The response includes a details string naming the first offending field, e.g. "data: Required". Unknown fields are rejected too — the schema is strict.
• 401 — the Authorization header (or key parameter on render) is missing, malformed, or the key is invalid or revoked.
• 403 — your plan doesn't include the feature; currently this means calling bulk generation without a Pro plan.
• 429 — monthly quota and credits are exhausted.
• 500 — something went wrong on our side; safe to retry with backoff.

Error format

JSON endpoints return:

{ "error": "Rate limit exceeded", "reason": "Monthly limit reached" }

The render endpoint returns plain-text errors instead, since its consumers are image tags.

Handling 429s well

• Track meta.remaining in your responses and slow down before you hit zero.
• A 429 will not resolve by retrying quickly — the quota resets at the start of the next calendar month. Either upgrade to Pro, buy credits, or back off until the reset.
• For high-volume needs, prefer bulk generation and browser-cached render URLs, both of which stretch a quota much further than repeated single calls.