Error Handling

All ApiOne errors follow a consistent JSON structure. Every error response includes a status field set to "error", a numeric code, a human-readable message, and a request_id for debugging.

Error response structure

{
  "status": "error",
  "code": 401,
  "message": "Invalid or missing API key",
  "request_id": "req_xyz789"
}

Full error code reference

HTTP status	Code string	Cause	Recommended action
400	`missing_param`	A required parameter (e.g. `domain`) is absent or empty	Check your request body and ensure all required fields are present
400	`invalid_param`	A parameter value is malformed (e.g. invalid domain format)	Validate input before sending. Domains should not include `https://` or paths.
401	`invalid_api_key`	API key is missing, malformed, or does not match any active key	Check the `X-API-Key` header. Regenerate the key from the Dashboard if needed.
402	`insufficient_credits`	Account has no remaining credits	Upgrade your plan or wait for the next billing cycle
404	`not_found`	No data found for the given input (domain, email, or name)	1 credit is deducted for the lookup. Try a different input or check spelling.
422	`unprocessable`	Input is syntactically valid but cannot be processed (e.g. parked domain)	Skip this record or flag for manual review
429	`rate_limit_exceeded`	Request rate exceeded for your plan	Wait for the `retry_after` seconds specified in the response, then retry
500	`internal_error`	Unexpected server-side error	Retry with exponential backoff. If the error persists, contact support with the `request_id`.
503	`service_unavailable`	ApiOne is temporarily unavailable	Retry after 30 seconds. Check status at apione.store/status.

Debugging with request_id

Every response — success or error — includes a request_id. This is a unique identifier for the specific API call. If you need to report an issue to ApiOne support, always include the request_id. It allows the support team to trace the exact request, inputs, and processing steps.

Retry logic

The following error codes are safe to retry automatically:

429 rate_limit_exceeded — wait for retry_after seconds
500 internal_error — retry with exponential backoff (1s, 2s, 4s)
503 service_unavailable — retry after 30 seconds

Do not retry 400, 401, 402, 404, or 422 errors automatically — these indicate a problem with the request itself that will not resolve on retry.

Contacting support

For persistent errors, email [email protected] with the request_id, the endpoint you called, and the full error response body.