Errors

Handle Circadify REST API errors — structured error responses, error codes, and retry strategies.

The Circadify API uses standard HTTP status codes and returns structured error responses to help you diagnose and handle failures.

Error Response Format

Most API errors follow this structure:

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded",
  "retryable": true
}

Rate-limited and quota responses use HTTP 429 with the body above; the API does not emit Retry-After or X-RateLimit-* headers, so apply your own backoff.

Session result failures return the session status plus an error message so SDKs can map the failure to their client-side error type.

Error Codes

Authentication Errors (401)

Authorization Errors (403)

Accessing a session that belongs to another developer does not return 403 — it returns 404 SESSION_NOT_FOUND, so cross-tenant session existence is hidden. A session you don't own looks like a 404. There is no DEVELOPER_PENDING or DEVELOPER_NOT_VERIFIED error: a pending account gets 403 DEVELOPER_SUSPENDED, and an unverified email surfaces as 401 UNAUTHORIZED.

Request Errors (400)

Not Found (404)

Conflict (409)

Signup does not emit an email-conflict error — POST /developer/signup returns the same generic 201 response whether or not the email already exists, to prevent email enumeration.

Gone (410)

Processing Failed (422)

When processing fails, the result poll returns 422 with { "session_id", "status": "failed", "error": "<message>" } — no error envelope. failed is a session status, not an error code. Start a new measurement and retry under better scan conditions.

Rate Limiting & Quota (429)

Server Errors (500)

There is no SERVICE_UNAVAILABLE error code, and INFERENCE_FAILED is not emitted in the session flow — a processing (inference) failure surfaces on the result poll as 422 with { "session_id", "status": "failed", "error": "<message>" }.

HTTP Status Code Summary

Retry Strategy

For retryable errors (retryable: true), implement exponential backoff:

async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);
 
    if (response.ok) return response;
 
    const body = await response.json();
 
    // Honor the `retryable` flag: don't retry non-retryable client errors.
    // Note a 429 can be QUOTA_EXCEEDED (retryable: false) — don't retry it.
    if (response.status < 500 && body.retryable === false) {
      throw new Error(body.message);
    }
 
    if (attempt === maxRetries) {
      throw new Error(body.message);
    }
 
    // No Retry-After header is emitted — use exponential backoff
    const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
 
    await new Promise(resolve => setTimeout(resolve, delay));
  }
}

Recommended parameters:

Next Steps

• Rate Limits — Understand and manage rate limits
• Sessions — Session endpoints and lifecycle
• SDK Error Codes — Client-side error reference