Errors

Error responses use a single JSON shape:

{
  "error": {
    "type": "invalid_request_error",
    "code": "NOT_FOUND",
    "message": "Resource not found.",
    "request_id": "01H…",
    "details": {
      "resource": "subscriber",
      "id": "01H…"
    }
  }
}

Clients show error.message. Branch on code and HTTP status. Do not parse details to invent copy. Include request_id when you contact support.

This follows the Plat5 envelope. Fallback sentences match Plat5; e10s-specific 422/409 copy is set at the throw site.

Types

type	Use
invalid_request_error	4xx — bad input or business rule
api_error	5xx — something failed on our side

Common codes

The fallback message is used only when nothing more specific applies.

HTTP	code	Fallback message	When
401	UNAUTHORIZED	Authentication required.	Missing or invalid credentials
404	NOT_FOUND	Resource not found.	Unknown id, or not in your organization
409	CONFLICT	That already exists.	Duplicate key, active subscription exists, feature still on a plan/override, delete blocked
422	VALIDATION_ERROR	That doesn't look right.	Bad body or query (including unknown feature key on check)
500	INTERNAL_ERROR	An unexpected error occurred.	Unexpected server error
503	SERVICE_UNAVAILABLE	Service temporarily unavailable.	Temporary outage; safe to retry with backoff

UNAUTHORIZED / NOT_FOUND / INTERNAL_ERROR / SERVICE_UNAVAILABLE stay generic on purpose.

Details

details is optional and depends on code (e.g. validation fields, or resource + id for not found). Never the only place the human sentence lives.