Error reference

Error reference

Every error response shares the same envelope:

{
  "error": {
    "type": "https://docs.autohost.app/api/errors/<code>",
    "code": "<code>",
    "message": "<human readable>",
    "request_id": "req_…",
    "doc_url": "https://docs.autohost.app/api/errors/<code>",
    "param": "<optional, names the offending field>",
    "details": { … }
  }
}

The doc_url points back here. Click any code below for triage guidance and a sample body.

HTTP 401

Code	Retryable	Summary
authentication_required	No	No API key was supplied with the request.
invalid_api_key	No	The API key is malformed, unknown, expired, or revoked.

HTTP 402

Code	Retryable	Summary
payment_required	No	The org is entitled but cannot spend: its wallet is inactive or it has no credits.

HTTP 403

Code	Retryable	Summary
subscription_required	No	The org is not entitled: it has no active subscription (post-trial or lapsed).
insufficient_scope	No	The key is valid but lacks the scope required for this endpoint.
mode_mismatch	No	A live key was used to access a test resource (or vice versa).

HTTP 404

Code	Retryable	Summary
resource_not_found	No	The requested resource does not exist within your organisation.

HTTP 409

Code	Retryable	Summary
region_mismatch	No	The key was issued in a different region than the endpoint.
session_already_completed	No	The session is in a terminal state and cannot be modified.
idempotency_conflict	No	The same `Idempotency-Key` was reused with a different request body.
version_conflict	Yes	Optimistic concurrency check failed.

HTTP 410

Code	Retryable	Summary
org_shredded	No	The organization has been crypto-shredded under Article 17 (right to erasure); its data is no longer accessible.

HTTP 413

Code	Retryable	Summary
payload_too_large	No	The request body exceeded the per-endpoint size limit.

HTTP 415

Code	Retryable	Summary
unsupported_media_type	No	The request `Content-Type` is not accepted for this endpoint.

HTTP 422

Code	Retryable	Summary
validation_error	No	The request body or query parameters failed schema validation.

HTTP 429

Code	Retryable	Summary
rate_limit_exceeded	Yes	The caller exceeded its rate limit.

HTTP 500

Code	Retryable	Summary
internal_error	Yes	An unhandled error occurred inside the API.

HTTP 502

Code	Retryable	Summary
provider_error	Yes	An upstream provider (KYC vendor, bureau, etc) failed.

HTTP 503

Code	Retryable	Summary
billing_unavailable	Yes	The billing-state cache could not be read; the request was refused to avoid silently bypassing quota.