API errors

Contact Button API v1 returns failures as RFC 9457-style problem details with the media type application/problem+json. API-host errors and unknown /v1 paths use the same JSON contract, so an agent does not need to parse an HTML error page.

{
  "type": "https://docs.contactbutton.com/reference/errors#http-401",
  "title": "Authentication required",
  "status": 401,
  "code": "authentication_required",
  "detail": "Provide a valid Contact Button API key as a Bearer token.",
  "resolution": "Create or rotate a scoped key, then retry with a Bearer token.",
  "instance": "/v1/workspaces",
  "request_id": "01k..."
}

Every error also returns X-Request-ID, Contact-Button-API-Version, and Cache-Control: no-store. A 401 response includes a standard WWW-Authenticate: Bearer challenge.

Stable error codes

HTTP status	Code	Agent behavior
`401`	`authentication_required`	Obtain or rotate a scoped key; never ask a human to paste it into model context
`403`	`forbidden`	Request only the missing least-privilege scope
`404`	`resource_not_found`	Re-read the OpenAPI path and resource identifier
`409`	`conflict`	Read current state, reconcile it, and retry with a new idempotency key when applicable
`422`	`validation_failed`	Correct the fields in `errors` and retry
`429`	`rate_limit_exceeded`	Wait and use exponential backoff
`500`	`internal_error`	Retry later and report the request ID if it persists

Treat code as the programmatic branch condition. Display detail to a developer when useful, and follow resolution only within the represented human’s existing authority.

Get started

Build

Operate

Stable error codes

​Stable error codes

Stable error codes