Error Codes

All API errors return a consistent JSON structure:

{
  "error": "Bad Request",
  "message": "customer_id is required",
  "status": 400
}

HTTP Status Codes

Status	Title	Description	Recovery
`400`	Bad Request	The request body is invalid or missing required fields	Check the request body against the API schema. Ensure all required fields are present and correctly typed.
`401`	Unauthorized	The API key is missing, invalid, or the `X-Tenant-ID` header is missing	Verify your API key is correct and active. Check that the Authorization header uses the `Bearer` prefix and the `X-Tenant-ID` header contains a valid UUID.
`403`	Forbidden	The API key doesn't have permission for this operation	Check that your API key has the required scope. Sandbox keys cannot access production endpoints.
`404`	Not Found	The requested resource doesn't exist	Verify the resource ID is correct. The profile, signal, or rule may have been deleted or belong to a different tenant.
`409`	Conflict	The request conflicts with the current resource state	Check the current status. Some operations are only valid in certain states (e.g., signal review requires `ACTIVE` status).
`429`	Rate Limited	Too many requests — you've exceeded the rate limit	Implement exponential backoff. Check the `Retry-After` header for when to retry. See Rate Limits.
`500`	Internal Server Error	An unexpected error occurred on the server	Retry the request with exponential backoff. If the error persists, contact support.

Code	Description	Example message	HTTP Status
`VALIDATION_ERROR`	Request body validation failed	`customer_id is required`	400
`PROFILE_NOT_FOUND`	Elder profile does not exist	`profile not found`	404
`SIGNAL_NOT_FOUND`	Exploitation signal does not exist	`signal not found`	404
`RULE_NOT_FOUND`	Detection rule does not exist	`rule not found`	404
`BASELINE_NOT_FOUND`	Behavioral baseline does not exist	`baseline not found`	404
`BATCH_RUN_NOT_FOUND`	Batch run does not exist	`batch run not found`	404
`INVALID_STATE`	Operation not valid in current state	`signal status must be CONFIRMED or DISMISSED`	409
`INVALID_STATUS_TRANSITION`	Invalid profile status transition	`cannot transition from DECEASED to ACTIVE`	409
`RATE_LIMIT_EXCEEDED`	Too many requests	`Rate limit exceeded. Please retry after the reset time.`	429
`TENANT_NOT_FOUND`	Tenant ID is invalid	`missing tenant ID`	401
`INVALID_ENROLLMENT_REASON`	Invalid enrollment reason provided	`invalid enrollment_reason`	400
`INVALID_SIGNAL_CATEGORY`	Invalid signal category	`invalid signal_category`	400
`INVALID_RULE_TYPE`	Invalid rule type	`invalid rule_type`	400
`INVALID_SEVERITY`	Invalid severity level	`invalid severity`	400
`INVALID_WEIGHT`	Rule weight out of range	`weight must be between 0 and 1`	400

{
  "error": "Unauthorized",
  "message": "missing tenant ID",
  "status": 401
}

Fix: Add the X-Tenant-ID header with your tenant UUID to every request.

{
  "error": "Bad Request",
  "message": "invalid profile ID",
  "status": 400
}

Fix: Ensure the profile ID is a valid UUID. Profile IDs are returned when you create a profile.

{
  "error": "Bad Request",
  "message": "status must be CONFIRMED or DISMISSED",
  "status": 400
}

Fix: When reviewing a signal, the status must be either CONFIRMED or DISMISSED.

{
  "error": "Bad Request",
  "message": "customer_name is required",
  "status": 400
}

Fix: Ensure customer_id, customer_name, date_of_birth, and enrollment_reason are all provided.

Retry with backoff — For 429 and 5xx errors, implement exponential backoff starting at 1 second
Check status before operations — Call GET /profiles/{id} to check the current state before performing actions
Validate locally first — Validate required fields and enum values client-side before sending API requests
Handle idempotently — Use the profile id or customer_id to track enrollments and avoid duplicates
Use sandbox for testing — Use test customer name patterns in sandbox for deterministic results