Errors and limits

Error format, error codes, and request limits.

Error format

Errors use standard HTTP status codes and a consistent JSON body:

400 Bad Request

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The message field is required."
  },
  "request_id": "req_6yN1sQ8vKb2LmZ0e"
}

Branch on error.code, which is stable. error.message is meant for people and may change. Error responses never include stack traces or details from upstream services.

Error codes

Status	Code	Meaning
400	INVALID_REQUEST	The body is not valid JSON or fails validation. The message names the field.
401	UNAUTHORIZED	The API key is missing, malformed, unknown, or revoked.
402	BILLING_PAYMENT_REQUIRED	Paid usage is blocked: an invoice is unpaid, or Pay As You Go has no payment method. Resolve it in the billing dashboard. Unused free requests still work.
404	NOT_FOUND	The requested API does not exist. Check the product and operation in the path.
413	PAYLOAD_TOO_LARGE	The request body is over the size limit.
415	UNSUPPORTED_MEDIA_TYPE	The Content-Type header is not application/json.
422	UNPROCESSABLE_CONTENT	The input could not be evaluated. Retrying the same input is unlikely to help.
429	RATE_LIMITED	The workspace exceeded its per-minute request limit. Retry after the Retry-After header.
429	USAGE_LIMIT_EXCEEDED	The workspace reached its monthly allowance (Free) or its spending cap (Pay As You Go). Don't retry until the limit changes or the next UTC month starts.
500	INTERNAL_ERROR	Something failed on our side. Retrying is safe.
503	SERVICE_UNAVAILABLE	The API is temporarily unavailable or not yet configured. Retry later.
504	TIMEOUT	Processing took too long. Retrying is safe.

Rate limits

Each workspace can make 10 requests per rolling minute on Free and 60 on Pay As You Go, across all of its keys and the playground. Over the limit, the API returns 429 RATE_LIMITED with a Retry-After header in seconds. If you need a higher limit, contact us.

Monthly usage limits

Usage is counted per workspace per UTC calendar month, across all keys and the playground. A request counts once it completes successfully (a 2xx response, including results such as unknown or requires_review). Rejected and failed requests (4xx, 5xx) never count.

Free includes 1,000 requests a month. After that, requests return 429 USAGE_LIMIT_EXCEEDED until the next month.
Pay As You Go includes the same free requests, then bills each successful request up to your monthly spending cap. At the cap, requests return 429 USAGE_LIMIT_EXCEEDED.
If an invoice is unpaid or no payment method is saved, paid requests return 402 BILLING_PAYMENT_REQUIRED until it's resolved; unused free requests keep working.

Retries

Retry 429 RATE_LIMITED, 500, 503, and 504 with exponential backoff. Don't retry 429 USAGE_LIMIT_EXCEEDED, 402, or other 4xx responses without changing the request or your billing settings.