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

# API errors

> Diagnose public API authentication, scope, validation, conflict, and rate-limit responses.

Canary public API errors use RFC 7807 Problem Details with the `application/problem+json` content type. Read the HTTP status together with `code`, `detail`, `validation_errors`, and `request_id`.

## Error shape

```json theme={"theme":"github-light"}
{
  "type": "https://api.oncanary.com/errors/validation_error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "request_id": "req_01...",
  "code": "validation_error",
  "validation_errors": [
    { "field": "name", "message": "Required" }
  ]
}
```

The same request ID is returned in the `X-Request-ID` response header. Save it with your integration logs.

## Resolve common statuses

### 400 Bad Request

Review `validation_errors`, query parameter names, enum values, timestamps, and JSON types. For list requests, an invalid or stale cursor can return `invalid_cursor`; restart from the first page.

### 401 Unauthorized

1. Send `Authorization: Bearer sk_test_...` or `Authorization: Bearer sk_live_...`.
2. Confirm the `Bearer` scheme and spacing.
3. Confirm the secret has its complete prefix and value.
4. Replace a revoked, expired, or unknown key.

### 403 Forbidden

The key lacks the required scope or the operation has another authorization boundary. Read `detail` for the required scope, then create a new least-privilege key when broader access is intended.

### 404 Not Found

Confirm the resource ID, endpoint path, and owning organization. Canary scopes resources to the organization associated with the key, so an ID from another organization resolves as unavailable.

### 409 Conflict

Resolve the specific conflict before retrying. An `identifier_conflict`, for example, means the exact active value already belongs to another record in the organization.

### 429 Too Many Requests

Honor `Retry-After`. Use `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` to pace requests, add bounded backoff, and avoid synchronized retries.

### 500 Server Error

Retry read requests with bounded exponential backoff. Review the latest resource state before retrying a write. If the error persists, contact support with the request ID, timestamp, method, path, and response code.

## Safe logging

Log the method, path, status, problem code, request ID, and retry metadata. Redact the `Authorization` header, full API key, attachment content, and sensitive request fields.

## Related pages

* [Authentication](/authentication)
* [API errors guide](/guides/errors)
* [Rate limits](/guides/rate-limits)
* [Pagination](/guides/pagination)