Error Handling

HTTP status codes, error response format, and common errors.

Error Response Format

All error responses from the Warm AI API follow a consistent JSON structure:


{
  "error": true,
  "message": "A human-readable description of the error",
  "code": "ERROR_CODE"
}

Field	Type	Description
`error`	boolean	Always `true` for error responses
`message`	string	Human-readable error description
`code`	string	Machine-readable error code

HTTP Status Codes

Status	Meaning	Description
200	Success	Request completed successfully
202	Accepted	Request accepted and is being processed asynchronously
400	Bad Request	Invalid request body, missing required fields, or malformed input
401	Unauthorised	Missing or invalid `x-access-key` or `x-user-id` header
402	Payment Required	Insufficient credit balance to complete the operation
403	Forbidden	Valid credentials but insufficient permissions for this action
404	Not Found	The requested resource does not exist
409	Conflict	The request conflicts with the current state (e.g. duplicate idempotency key)
429	Too Many Requests	Rate limit exceeded
500	Server Error	An unexpected error occurred on the server

Common Errors

`INVALID_ACCESS_KEY`

Cause: The x-access-key header is missing, malformed, or does not match any active API key.

Solution: Verify your access key is correct and has not been revoked. Regenerate a new key from the dashboard if needed.

`INVALID_USER_ID`

Cause: The x-user-id header does not match any user connected to your API key.

Solution: Use the List Users endpoint to get valid user IDs, or check that the user has completed the connect flow.

`INVALID_PROSPECT_URL`

Cause: The provided LinkedIn URL is not a valid LinkedIn profile URL.

Solution: Ensure the URL follows the format https://linkedin.com/in/username or https://www.linkedin.com/in/username. Remove any query parameters or trailing slashes.

`RESEARCH_NOT_FOUND`

Cause: The specified research_id does not exist or has expired.

Solution: Research results are retained for a limited time. Re-run the research operation if the original result has expired.

`USER_NOT_CONFIGURED`

Cause: The user has not completed the Setup Wizard or is missing required settings (e.g. product, CTA preference).

Solution: Ensure the user has completed all 4 steps of the Setup Wizard, or configure their settings via the User Settings API.

`INSUFFICIENT_BALANCE`

Cause: Your account does not have enough credits to complete the requested operation.

Solution: Top up your credit balance from the dashboard, or enable auto-reload in your Account Settings.

`RATE_LIMITED`

Cause: Too many requests sent in a short period of time.

Solution: Back off and retry after the period indicated in the response. See Rate Limiting below.

Best Practices

Follow these guidelines to build a resilient integration with the Warm AI API:

Generate a new idempotency key for each unique request to avoid duplicate operations.
Reuse the same idempotency key when retrying a failed request to ensure it is not processed twice.
Use exponential backoff when retrying after errors — start with 1 second and double the delay each attempt.
Store the research_id returned from research operations so you can retrieve results later without re-running.
Cache User Research results on your side to reduce API calls and credit usage.
Validate LinkedIn URLs before sending them to the API to avoid unnecessary INVALID_PROSPECT_URL errors.

Rate Limiting

When you exceed the rate limit, the API returns a 429 Too Many Requests response.

Response Headers:

Header	Description
`Retry-After`	Number of seconds to wait before retrying

Response Body:


{
  "error": true,
  "message": "Rate limit exceeded. Please retry after the specified period.",
  "code": "RATE_LIMITED",
  "retry_after_ms": 5000
}

Field	Type	Description
`retry_after_ms`	number	Milliseconds to wait before retrying

Implement exponential backoff in your retry logic and respect the Retry-After header to avoid further throttling.