Documentation

Errors

Error shape, codes, and which ones to retry.

Every error uses one shape. retryable says whether the same request may succeed if repeated.

{
  "error": {
    "message": "Rate limit reached (60 requests per minute). Retry in 12s.",
    "type": "friday_error",
    "code": "rate_limited",
    "retryable": true,
    "request_id": "req_..."
  }
}

429 responses include a Retry-After header in seconds. 503 upstream_busy sends Retry-After: 5. Quote the request_id when you contact support. If a stream fails after it started, the error object arrives as a data line, followed by [DONE].

Status	Code	Retryable	When
400	`invalid_request`	No	Malformed or missing field (model, messages, input, prompt, file, ...).
400	`invalid_json`	No	The body is not valid JSON.
400	`unsupported_parameter`	No	A parameter this endpoint does not support yet (for example tools or response_format), or n other than 1 on images.
400	`wrong_endpoint`	No	The model does not belong to this endpoint (for example a chat model on /images/generations).
400	`max_tokens_too_large`	No	max_tokens is above the model's maximum output tokens.
400	`invalid_idempotency_key`	No	Idempotency-Key is longer than 200 characters.
400	`upstream_rejected`	No	The model provider rejected the parameters or input. Not charged.
401	`missing_api_key`	No	No Authorization: Bearer header.
401	`invalid_api_key`	No	Unknown key.
401	`api_key_revoked`	No	The key was revoked.
401	`api_key_expired`	No	The key passed its expiry.
402	`insufficient_balance`	No	Available balance is below the worst-case reservation. Add funds or lower max_tokens.
402	`org_budget_exceeded`	No	Would pass the organization's monthly hard cap.
402	`project_budget_exceeded`	No	Would pass the project's monthly hard cap.
402	`key_budget_exceeded`	No	Would pass the key's spend cap.
403	`account_suspended`	No	The organization or key owner is suspended.
403	`api_paused`	No	API access is paused for the organization.
403	`project_archived`	No	The key's project is archived.
403	`model_not_allowed`	No	The key's allowed-models list excludes this model.
404	`model_not_found`	No	Unknown or inactive model id.
404	`agent_not_found`	No	The agent is not in this organization.
409	`duplicate_request`	No	This Idempotency-Key already ran with the same body. Not run or charged again.
413	`request_too_large`	No	JSON body larger than 2 MB.
413	`input_too_large`	No	Chat input is larger than 400,000 characters.
413	`file_too_large`	No	Audio file larger than 25 MB.
415	`unsupported_media_type`	No	Wrong Content-Type (send application/json, or an audio file for transcription).
422	`idempotency_key_reused`	No	This Idempotency-Key was used with a different body.
429	`rate_limited`	Yes	Per-key or per-organization requests per minute reached. See Retry-After.
429	`concurrency_limit`	Yes	Too many requests in progress for the organization.
499	`client_cancelled`	No	The request was cancelled by the client.
500	`internal_error`	Yes	Something went wrong on our side.
502	`model_unavailable`	Yes	The model could not complete the request, or returned nothing. Not charged.
502	`gateway_unavailable`	Yes	The model service is not reachable. Not charged.
503	`upstream_busy`	Yes	The model is at capacity (Retry-After: 5). Not charged.
503	`price_unavailable`	No	The model has no active price yet.
504	`upstream_timeout`	Yes	The model did not answer within 120 seconds. Not charged.