Errors & Rate Limits

Diagnose authentication, permission, balance, validation, and throttling failures.

Errors and rate limits

Treat errors as explicit product states. Do not hide them behind silent retries.

Common status codes

Status	Meaning	What to do
400	Invalid request shape, unsupported mode, bad scope, or schema mismatch.	Check model, mode, input, params, and scope.
401	Missing or invalid authentication.	Send X-API-Key for server requests or a valid bearer token for signed-in flows.
402	Payment or wallet state prevents execution.	Check Billing and wallet balance for the active workspace.
403	The credential is valid but lacks permission.	Confirm workspace membership and API key permissions.
404	Model or resource was not found.	Verify the model slug and that the model is published.
409	Conflicting model identity or state.	Re-check the slug and retry only after correcting the conflict.
429	Rate limit exceeded.	Respect Retry-After and reduce request volume.
502	Upstream control plane or runtime failure.	Retry later only if the operation is safe and visible to the user.

Rate-limit headers

Responses can include:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1710000000
Retry-After: 60

If you receive 429, wait for Retry-After before making another request.

Schema errors

Schema errors usually mean the API request does not match the model contract. Open the model in Playground, run the same operation, and compare the generated input shape with your integration payload.

Balance errors

Balance errors mean the active workspace cannot pay for the requested usage. Open Billing, check wallet status, payment methods, and usage summary, then retry only after the workspace is active and funded.