Guides

Rate limits & errors

Rate-limit headers, error responses, and request limits.

Rate limits

Rate limits apply to generation endpoints. Check your current values in GET /v1/info under limits, or contact hello@kalpalabs.ai for a higher limit.

Header	Meaning
`X-RateLimit-Limit`	Requests allowed per minute
`X-RateLimit-Remaining`	Requests currently available
`X-RateLimit-Reset`	Seconds until the limit resets

When you reach the limit, the API returns 429 with Retry-After:

json

{ "error": { "type": "rate_limit_exceeded", "message": "Rate limit exceeded (600 requests/min). Retry in 2s.", "request_id": "…" } }

Wait for Retry-After before retrying.

The error envelope

REST errors use one response shape:

json

{ "error": { "type": "…", "message": "…", "request_id": "…" } }

Validation errors may also include error.details. SSE and WebSocket streams send errors as protocol events after streaming begins.

Status	`type`	Meaning
`400`	`invalid_request`	Invalid request, audio, model, or conversation.
`400`	`context_length_exceeded`	Generation filled the model's context window before a stop token. Try shorter sentences.
`401`	`authentication_error`	Missing or invalid API key.
`404`	`not_found`	Path or voice not found.
`405`	`method_not_allowed`	HTTP method not supported.
`422`	`invalid_request`	Request body does not match the schema.
`429`	`rate_limit_exceeded`	Rate limit reached.
`500`	`internal_error`	Unexpected server error.
`502`	`inference_error`	Model backend error or timeout.
`503`	`service_unavailable`	API-key verification is temporarily unavailable.

Request caps

Current request limits are also available from GET /v1/info:

Limit	Current value
Text per request or turn	8,000 characters
Turns per REST/SSE conversation	64
Audio per turn	25 MiB decoded WAV

Debugging a failed call

Use error.type in application logic and message for display. For persistent failures, share the request_id with support; it also appears in the X-Request-ID response header.