Errors

Every non-2xx response from Patomic uses the same envelope. Once your client knows this shape, it knows every failure.

The envelope

{
  "error": {
    "type": "authentication_error",
    "code": "unauthorized",
    "message": "Missing or invalid API key.",
    "param": null,
    "docs_url": "https://docs.patomic.dev/errors/unauthorized",
    "request_id": "9f8d3584ad538cad",
    "suggestion": "Send your API key as `Authorization: Bearer ptmc_…`. Verify the key is active in your dashboard."
  }
}

Every field is always present (with null for the optional ones). No schema branches based on error type.

Field reference

Field	What it’s for
type	Broad bucket for client-side dispatch — authentication_error, rate_limit_error, invalid_request_error, idempotency_error, not_found_error, internal_error. Stable. Use for retry vs. fix vs. escalate decisions.
code	Specific machine-readable reason — unauthorized, rate_limit_exceeded, invalid_parameter, invalid_idempotency_key, idempotency_key_conflict, not_found, internal_error. Stable.
message	Human-readable description, no PII.
param	Which input parameter caused the error, when applicable (e.g. "expires_at", "cursor"). null when not applicable.
docs_url	Stable link to a docs page about this exact code. Always present.
request_id	Patomic’s internal correlation id (= the cf-ray you’d see in logs). Include in any support ticket.
suggestion	An actionable hint — what to do next. null only when there’s nothing meaningful to suggest.

Why this shape

• Type + code separation lets you write a single retry-vs-fix-vs-escalate switch on type without ever needing to enumerate every code.
• Always-present docs_url means a developer hitting a 401 in their app can click the URL Patomic returned and read this page within 5 seconds.
• Always-present request_id correlates with Patomic’s own logs. Include it in support tickets and we can find the request in under 30 seconds.
• No leaked sub-reasons on auth. All authentication failures (missing / malformed / unknown / revoked / expired) collapse to one externally-visible code: "unauthorized". The audit log keeps the precise reason for forensics; the response does not. This is intentional and security-tested.

Per-code references

See the Error reference section in the sidebar for one page per code, each with cause, fix and example response.