Skip to main content
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

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.