Errors

Every failure returns the same machine-readable envelope — a closed set of types and codes, never a stack trace. Agents and scripts branch on code; humans read message. The request_id ties the failure to our logs — include it in bug reports.

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "No deck with that id.",
    "param": "id",
    "request_id": "req_8f2c4a1b",
    "doc_url": "https://docs.renza.io/errors/resource_not_found"
  }
}

Error types

Error codes

The closed set — every code the API can return, each with its own page (the doc_url in the envelope links straight to it):

• parameter_missing — A required parameter wasn't provided
• parameter_invalid — A parameter was provided but its value is malformed or out of range — wrong type, unknown enum value, out-of-bounds number, or an id that doesn't belong where it was used
• resource_not_found — No resource matches that id (or external_id) within the active org
• resource_already_exists — Creating this resource collided with one that already exists (a uniqueness constraint).
• resource_unavailable — The resource exists but isn't in a state where this operation applies — for example, permanently deleting a deck that hasn't been trashed first.
• validation_failed — The request was well-formed but failed a semantic rule — the message says which.
• org_required — The request needs an org context and none was resolved
• access_denied — You're authenticated, but this credential doesn't have the right to do this — wrong org, insufficient role on the resource, or a scope the key lacks.
• plan_required — This operation is gated by the org's plan.
• idempotency_conflict — An Idempotency-Key was reused with a different request body, or the original request with this key is still in flight.
• rate_limited — Too many requests in a window.
• internal_error — Something failed on Renza's side