Error handling

The data API returns an OpenAI-compatible error body: {"error":{"type":"…","code":"…","message":"…","param":null}}. It does not use the control-plane envelope.

code	HTTP	Message	Recommended action
invalid_api_key	401	The key is invalid, revoked, or expired	Check the key, then create or rotate it from API Keys
insufficient_credits	402	The available balance is insufficient or negative	Purchase a top-up or renew the current plan
entitlement_expired	403	The plan has expired	Renew the plan
entitlement_model_not_allowed	403	The current plan or key does not allow this model	Review the plan and key model allowlist, then select an allowed model
rate_limited	429	An RPM, TPM, or concurrency limit was exceeded	Reduce the request rate, retry with backoff, and review key and plan limits
settlement_degraded	503	The service is busy	Try again later and check the status page
upstream_error	502	The model service is temporarily unavailable	Retry with backoff or select another model, and check the status page
invalid_request_error	400	The request parameters are invalid	Correct the request using the safe error message and documentation

Do not log a full error response, key, prompt, or response. For diagnosis, retain only the HTTP status, safe error code, and X-Request-Id.