Errors

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

Error Response Format

All errors follow this structure:

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

Field	Type	Description
error	string	Machine-readable error code
message	string	Human-readable description
retryable	boolean	Whether the request can be retried

Rate-limited responses also include a Retry-After header with the number of seconds to wait.

Error Codes

Authentication Errors (401)

Code	Description	Resolution
API_KEY_INVALID	The API key is missing, malformed, revoked, or expired	Check your key in the developer dashboard. Create a new key if needed.
UNAUTHORIZED	Bearer token is missing or invalid	Re-authenticate and obtain a fresh token.

Tip

All API key validation failures return the same API_KEY_INVALID code regardless of the specific reason (missing, revoked, expired, or malformed). This prevents attackers from enumerating valid keys. After 10 consecutive failed attempts, the key is temporarily locked out for 15 minutes.

Authorization Errors (403)

Code	Description	Resolution
FORBIDDEN	You do not have permission to access this resource	Verify the session belongs to your account.
DEVELOPER_PENDING	Your account is awaiting approval	Wait for the approval email or contact support.
DEVELOPER_SUSPENDED	Your account has been suspended	Contact support to resolve.
DEVELOPER_NOT_VERIFIED	Your email address has not been verified	Check your inbox for the verification email.

Request Errors (400)

Code	Description	Resolution
INVALID_REQUEST	Missing or invalid request parameters	Check the request body and path parameters against the endpoint documentation.
VERIFICATION_TOKEN_INVALID	Email verification or password reset token is invalid or expired	Request a new verification email or password reset.

Not Found (404)

Code	Description	Resolution
SESSION_NOT_FOUND	The session ID does not exist	Sessions expire after a short time. Create a new session.
DEVELOPER_NOT_FOUND	No developer account found for this identifier	Check the account exists and the ID is correct.

Conflict (409)

Code	Description	Resolution
EMAIL_ALREADY_EXISTS	An account with this email already exists	Log in with the existing account or use a different email.

Gone (410)

Code	Description	Resolution
SESSION_EXPIRED	The session timed out before completion	Create a new session and retry the measurement.

Rate Limiting (429)

Code	Description	Resolution
RATE_LIMIT_EXCEEDED	You have exceeded the hourly request limit for your plan	Wait for the Retry-After period, then retry. See Rate Limits.
QUOTA_EXCEEDED	You have exceeded the monthly scan limit for your plan	Upgrade your plan or wait for the next billing cycle.

Server Errors (500/503)

Code	Description	Resolution
INTERNAL_ERROR	An unexpected server error occurred	Retry with exponential backoff. If persistent, contact support.
INFERENCE_FAILED	The inference engine could not process the measurement	Retryable. The SDK automatically provides fallback vitals. Retry the full session.
SERVICE_UNAVAILABLE	A backend service is temporarily unavailable	Retryable. Wait and retry with exponential backoff.

HTTP Status Code Summary

Status	Meaning
200	Success
201	Created (e.g., new API key)
400	Bad Request — invalid parameters
401	Unauthorized — invalid or missing credentials
403	Forbidden — insufficient permissions
404	Not Found — resource does not exist
409	Conflict — resource state conflict
410	Gone — resource has expired
429	Rate Limited — too many requests
500	Internal Error — server-side failure
503	Service Unavailable — temporary backend issue

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();

    // Don't retry client errors (except rate limits)
    if (response.status < 500 && response.status !== 429) {
      throw new Error(body.message);
    }

    if (attempt === maxRetries) {
      throw new Error(body.message);
    }

    // Use Retry-After header if present, otherwise exponential backoff
    const retryAfter = response.headers.get('Retry-After');
    const delay = retryAfter
      ? parseInt(retryAfter, 10) * 1000
      : Math.min(1000 * Math.pow(2, attempt), 30000);

    await new Promise(resolve => setTimeout(resolve, delay));
  }
}

Recommended parameters:

Parameter	Value
Max retries	3
Initial delay	1 second
Max delay	30 seconds
Backoff multiplier	2x

Caution

Never retry 401 or 403 errors — these indicate a credentials or permissions issue that will not resolve with retries. Always respect the Retry-After header on 429 responses.

Next Steps

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