Error reference

All errors share one envelope (error.message, error.type, error.code). Branch on code — it stays stable where messages don't.

Your request

Status	Code	Where
400	bad_request	Malformed input — the message says exactly what to fix.
400	model_not_supported_for_endpoint	Right model, wrong endpoint — an embedding model sent to /v1/chat/completions, or the reverse.
400	batch_not_supported	This model can't be used with batch. Send the requests to /v1/chat/completions instead.
413	request_too_large	Inference body over 10MB; audio uploads over 50MB.
422	guardrail_blocked	Account guardrails stopped sensitive data leaving.

Your account

Status	Code	Where
401	invalid_api_key	Missing, revoked, disabled or expired key.
402	budget_exceeded	Hard spend cap reached for the period.
403	forbidden	Key lacks the required scope, or the account is suspended.
403	model_unavailable_under_budget	A hard cap is armed and this model can't be metered, so serving it would bypass the cap.
429	rate_limit_exceeded	Requests/min, tokens/min or concurrency cap. Has retry-after.
429	rate_limited	Too many failed authentication attempts from one source — check the key you're sending. One budget covers the gateway, the management API and MCP, so a bad key spent at one shows up at all three. Has retry-after.

The model

Status	Code	Where
404	model_not_found	No such model, or not one your key can use.
404	no_regional_route	Your account keeps traffic in-region and this model has no route there.
503	no_live_deployment	The model is in the catalogue but nothing can serve it right now. Safe to retry.

Us

Status	Code	Where
404	not_found	No such resource for you — Roar never reveals whether it exists for someone else.
502	upstream_error	The model could not be reached, including after failover. Safe to retry.
503	service_unavailable	A problem on our side, not with your request or your key. Has retry-after.
504	upstream_timeout	The model took too long; safe to retry.

Include the request id when contacting support. Every response carries it twice, under x-request-id and x-roar-request-id — same value, so either will do. If you use an official OpenAI SDK it is already on the error object as error.requestID.