Error codes

Every failure uses one envelope. code is stable and safe to branch on; message is for humans and may be reworded; details is either null or a small object such as {"field": "title"}.

{
  "success": false,
  "error": {
    "code": "SITE_EXPIRED",
    "message": "This registration has expired due to inactivity.",
    "details": null
  },
  "request_id": "req_9x2..."
}

The list

HTTP status summary

SDK-side error codes

The JavaScript SDK raises CreatorNotifyError with a code. API errors keep their API code; the SDK adds MISSING_WEBSITE_ID, UNSUPPORTED, PERMISSION_DENIED, PERMISSION_ERROR, SERVICE_WORKER_ERROR, NETWORK_ERROR, SUBSCRIPTION_CHANGED and UNKNOWN. See the SDK reference.

Handling errors well

const response = await fetch(`${API}/v1/notifications`, { method: 'POST', headers, body });
const body = await response.json().catch(() => null);

if (!response.ok) {
  const code = body?.error?.code ?? `HTTP_${response.status}`;
  switch (code) {
    case 'SITE_EXPIRED':
      alertOnCall('Registration expired — reactivate it');
      break;
    case 'RATE_LIMIT_EXCEEDED':
      await sleep(Number(response.headers.get('retry-after') ?? 30) * 1000);
      return retry();
    case 'INVALID_REQUEST':
      logValidation(body.error.details);
      break;
    default:
      logWithRequestId(response.headers.get('x-request-id'), code);
  }
  throw new Error(code);
}

Always log x-request-id. It is the only reliable way to correlate a user report with a Worker log line, and it never contains secrets.