Errors · Parsec docs

Failed requests are never charged.

Shape

/v1/systemone and the authentication and rate-limit errors on every /v1 endpoint use one envelope:

{"error": {"code": "bad_labels", "message": "question 'q': choice needs a criteria dict with >=2 labels"}}

/v1/pick reports validation errors as {"detail": "…"}. The Gemini API endpoints (/v1beta) return Google’s error shape.

The video endpoints (/v1/videos/*) use the OpenAI-style envelope:

{"error": {"message": "credit balance is empty; add credit at https://platform.parseclab.ai", "type": "billing_error", "code": "insufficient_quota"}}

Status	Code	Meaning
400	`invalid_request`, `invalid_json`, `unsupported_model`	No `model`, a body that is not a JSON object, or a model that is not a video model.
402	`insufficient_quota`	The account has no credit.
404	`model_not_found`, `not_found`	Unknown model, or a `request_id` this account did not start.
502	`upstream_error`	xAI failed.
504	`upstream_timeout`	xAI did not answer in time.

xAI’s own 4xx errors, such as a rejected prompt, come back unchanged. A generation that fails while rendering is not an HTTP error: its poll answers 200 with "status": "failed" (Grok Imagine).

Codes

Status	Code	Meaning
401	`unauthorized`	Missing, unknown or revoked key.
402	`insufficient_credit`	The account’s free decisions or credit are used up.
413	`state_too_long`	The state exceeds the 49,152-token context.
422	`no_questions`, `bad_question`, `bad_type`, `bad_labels`, `missing_state`, `bad_image`, `bad_request`	The request body is invalid; the message says which part.
503	`overloaded`	At capacity. Retry after the `Retry-After` header.
502	`backend_unavailable`	The model backend is down.
504	`timeout`	The model did not answer in time.

Retrying

Retry 503, 502 and 504 with exponential backoff, honouring Retry-After when it is present. Don’t retry 4xx responses without changing the request: they fail the same way every time.