> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contactbutton.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API errors

> Parse Contact Button API failures, resolve them safely, and correlate retries.

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.

```json theme={null}
{
  "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.


## Related topics

- [Authentication](/authentication.md)
- [Create a one-time Support payment intent](/api-reference/commerce/create-a-one-time-support-payment-intent.md)
- [Search Telnyx numbers and create short-lived price quotes](/api-reference/telephony/search-telnyx-numbers-and-create-short-lived-price-quotes.md)
- [Delete an unused form](/api-reference/forms/delete-an-unused-form.md)
- [Connect Telnyx or update phone capabilities](/api-reference/telephony/connect-telnyx-or-update-phone-capabilities.md)