Error catalog

Every error has one envelope

All public API errors return a JSON body with a single error object containing a numeric code matching the HTTP status and a human-readable message.

Envelope

{
  "error": {
    "code": 429,
    "message": "rate limit reached"
  }
}

Status codes

Status	Name	When it happens
`400`	Bad request	Malformed request body or unsupported request shape.
`401`	Unauthorized	Missing or invalid Hardcarrx API key.
`402`	Quota exceeded	Current plan or quota cannot accept this request.
`404`	Not found	Unknown resource — or, on /v1/responses, Responses compatibility is disabled on this deployment.
`422`	Unprocessable entity	Unsupported feature or malformed input (Responses-compat): tools, instructions, non-text modalities, or streaming. Explicit rejection — no silent emulation.
`429`	Rate limited	Rate limit reached. Back off and retry; do not retry immediately.
`500`	Provider or service error	The upstream provider or Hardcarrx service failed. Retry with backoff.

Retry guidance

429 and 500: retry with exponential backoff and jitter. Treat 429 as a signal to reduce concurrency, not to hammer the endpoint.
402: do not retry automatically. Resolve the plan or quota condition first (see usage endpoint).
401, 400, 404, 422: not retryable. Fix the request, credentials, or feature choice.