Skip to main content
All API errors return a consistent JSON format: 
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description"
  }
}

​
Error codes

StatusCodeDescription
400VALIDATION_ERRORInvalid request parameters
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENInsufficient permissions for this endpoint
404NOT_FOUNDResource not found (domain, technology, etc.)
409CONFLICTResource already exists
429RATE_LIMITRate limit exceeded — see rate limits
500INTERNAL_ERRORServer error — retry after a brief delay

​
Examples

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key"
  }
}
Fix: Check that your Authorization header includes a valid Bearer token. See how to get your API key.

​
How to handle errors

1

Check the status code

Use the HTTP status code for control flow. 2xx means success, 4xx means client error, 5xx means server error.
2

Read the error code

The error.code field provides a machine-readable error type you can switch on in your code.
3

Retry when appropriate

Retry on 429 (after Retry-After seconds) and 500 (with exponential backoff). Do not retry 400, 401, 403, or 404.
Always check success: false in the response body in addition to HTTP status codes. This gives you both the error code and a human-readable message for logging.

Rate limits

Request limits and retry strategies for 429 errors.

Authentication

Fix 401 errors with proper API key setup.

Credits

Avoid credit exhaustion errors with usage monitoring.

Live detection

Resolve 404 errors with real-time scanning.

​
Frequently asked questions

Retry 429 (rate limit) after waiting the Retry-After header value, and 500 (server error) with exponential backoff. Do not retry 400 (validation), 401 (auth), 403 (permissions), or 404 (not found) — these require fixing the request itself.
The domain might not be in the pre-crawled database yet. Try the live detection endpoint (POST /v1/technology-lookup-live) for real-time scanning. Live detection costs 5 credits.