Errors

Merki returns JSON errors with a stable shape. Handle them by code, not by message text.

Quick path

Read the HTTP status and the error.code.
Retry 429 and 5xx with exponential backoff; do not retry 4xx except 429.
On 401, rotate the key instead of retrying.

Details

Status	Code	Meaning	Retry
400	`invalid_request`	Validation failed: unknown model, bad field, over context.	No — fix the request.
401	`invalid_key`	Missing, revoked, or unknown key.	No — rotate. See API keys.
402	`insufficient_credits`	Balance too low for the request.	No — top up. See Credits.
403	`forbidden`	Tier or verification does not cover this request.	No — check Access tiers.
404	`not_found`	Unknown endpoint or model name.	No — check Endpoints.
409	`refused`	Request refused under content policy.	No — see Content safety.
429	`rate_limited`	Over the rate limit. `Retry-After` is set.	Yes — back off. See Rate limits.
5xx	`upstream_error` / `internal_error`	Merki or a BYOK provider failed.	Yes — back off with jitter.

Error body:

{"error": {"code": "rate_limited", "message": "Slow down.", "retry_after": 12}}

Mid-stream failure

On streaming requests, a failure after the first chunk ends the stream. Only tokens actually delivered are billed. Re-issue the request; there is no resume. See Streaming and Usage.

Checklist

[ ] 401 triggers rotation, not retry.
[ ] 429 honors Retry-After.
[ ] Refusals are surfaced to the operator, not silently retried.

Next step

Tune request volume: Rate limits.