Errors & limits
Errors, auth, and rate limits
Reference error codes, auth edge cases, and the headers you should log in production clients.
Common errors
Application-level errors expose a stable { error, code } shape. The fastest path to recovery is to key your client behavior off the `code` field rather than raw error strings.
Error code reference
| Field | Type | Required | Description |
|---|---|---|---|
| missing_credential | 400 | No | No bearer token or api_key was provided for an authenticated route. |
| invalid_credential | 401 | No | Token/API key not found, expired, or revoked. |
| invalid_credentials | 401 | No | Incorrect email/password pair on login. |
| billing_required | 402 | No | Free credits are exhausted and billing is not active. Set up billing to continue programmatic inference after the initial 500 credits. |
| no_model_access | 403 | No | Account does not have access to the requested model. |
| model_not_found | 404 | No | The requested model id does not exist in catalog. |
| conflict | 409 | No | Resource conflict (e.g. duplicate key name or email already registered). |
| validation_error | 422 | No | Request body failed schema validation. |
| rate_limit_exceeded | 429 | No | Rate limit exceeded (1,000 rpm free; 1,000,000 rpm with billing). |
| grpc_error | 502 | No | Inference gateway encountered an error communicating with the upstream model service. |
Rate limits
Headers to log and respect
Log these headers alongside request ids and model ids. They help you distinguish account-level throttling, transient provider pressure, and client-side retry storms.
Rate-limit header reference
| Field | Type | Required | Description |
|---|---|---|---|
| x-ratelimit-limit | string | No | Configured request limit for the current window. |
| x-ratelimit-remaining | string | No | Remaining requests in the current rate-limit window. |
| x-ratelimit-reset | string (unix seconds) | No | Timestamp when the current window resets. |
| retry-after | string (seconds) | No | Returned when the upstream or gateway asks clients to slow down. |
Recovery playbook
Operational responses
401 or invalid credential
Validate the credential first, confirm you are using Bearer format, and rotate keys from `/account/keys` if the key was revoked or copied into the wrong environment.
402 billing required
Free tier accounts start with 500 API credits and each programmatic forecast request consumes credits until billing is active. Check remaining balance on your account page and set up billing before the balance reaches zero.
400 / 422 validation errors
Return to the canonical `model + inputs + parameters` shape, confirm required fields and value types, and inspect the operation contract from `/docs/forecast` or `/docs/api` before retrying.
429 or retry-after headers
Back off using `retry-after` when present, preserve idempotency where possible, and avoid burst retries from multiple workers at once.
502 gRPC error
The upstream inference gateway returned a gRPC error. Retry with a smaller horizon or shorter context window, then fail over to a different model if your workflow needs a second chance path.