Errors & Rate Limits

Error response format

Error responses return JSON with an error code and message:

{
  "error": "SOME_ERROR_CODE",
  "message": "Human readable message"
}

The X-Request-ID header is always included on all responses. Some error responses may also include a request_id field in the JSON body, but this is not guaranteed for every endpoint/status code. Use the header value when contacting support.

Error code reference

401 - Authentication errors

Invalid key format:

{
  "error": "INVALID_KEY_FORMAT",
  "message": "Invalid API key format"
}

Invalid or inactive key:

{
  "error": "INVALID_API_KEY",
  "message": "Invalid or inactive API key"
}

422 - Validation errors

Validation errors include a details array with field-level issues:

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid request parameters",
  "details": [
    {
      "field": "font_id",
      "message": "ensure this value is less than or equal to 90",
      "type": "value_error.number.not_le"
    }
  ]
}

429 - Rate limit exceeded

Per-endpoint rate limit:

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded for /generate: 500 requests per 1 minute(s)",
  "limit": 500,
  "endpoint": "/generate",
  "retry_after": 45
}

Monthly request quota exceeded (generate only):

{
  "error": "REQUEST_LIMIT_EXCEEDED",
  "message": "Request limit exceeded: 10000/10000 monthly requests used",
  "limit": 10000,
  "used": 10000,
  "period": "monthly",
  "reset_at": "2024-02-01T00:00:00Z"
}

500 - Server errors

Server errors include request_id for support:

{
  "error": "GENERATION_ERROR",
  "message": "Failed to generate image. Please try again later.",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Rate limit headers

When rate limiting applies, responses include:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the window
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait before retrying (on 429 only)

Per-endpoint rate limits

Rate limits are enforced per API key:

Endpoint	Limit
`POST /api/v1/generate`	500 requests / minute
`POST /api/v1/preview`	300 requests / minute
`GET /api/v1/fonts`	100 requests / minute

GET /api/v1/status does not require authentication and is not subject to per-key rate limiting.

Request quotas (billing limits)

Accounts may have monthly request quotas. These are enforced on /generate only and return 429 with REQUEST_LIMIT_EXCEEDED.

Request IDs

Every response includes the X-Request-ID header. You can supply your own X-Request-ID header on requests — the API will echo it back. This is useful for correlating requests in your logs with support inquiries.

Getting Started

Guides

Reference

Errors & Rate Limits

Error response format

Error code reference

401 - Authentication errors

422 - Validation errors

429 - Rate limit exceeded

500 - Server errors

Rate limit headers

Per-endpoint rate limits

Request quotas (billing limits)

Request IDs

​Error response format

​Error code reference

​401 - Authentication errors

​422 - Validation errors

​429 - Rate limit exceeded

​500 - Server errors

​Rate limit headers

​Per-endpoint rate limits

​Request quotas (billing limits)

​Request IDs

Error response format

Error code reference

401 - Authentication errors

422 - Validation errors

429 - Rate limit exceeded

500 - Server errors

Rate limit headers

Per-endpoint rate limits

Request quotas (billing limits)

Request IDs