Errors

The WillItTrack API uses a consistent error envelope across all endpoints. Every error response includes a type, code, human-readable message, and request ID for debugging.

Error Envelope

Error response

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_parameter",
    "message": "The 'url' parameter is required.",
    "request_id": "req_550e8400-e29b-41d4-a716"
  }
}

Field	Type	Description
type	string	Category of the error (see below).
code	string	Machine-readable error code for programmatic handling.
message	string	Human-readable description of the error.
request_id	string \| null	Unique request ID. Include this when contacting support. Also returned in the `X-Request-Id` response header.

Error Types

Type	HTTP Status	Description
invalid_request_error	400, 404, 409, 429	The request was malformed, missing required fields, or targeted a non-existent resource.
authentication_error	401, 403	The API key is missing, invalid, revoked, or expired.
usage_limit_error	402	Free tier exhausted and insufficient credits to complete the request.
api_error	500, 503	An internal error occurred or a dependent service (scanner, database) is unavailable.

Error Codes

Use the code field for programmatic error handling rather than parsing the message string.

Code	Description
missing_parameter	A required field is missing from the request body.
invalid_parameter	A field has an invalid value (e.g. unknown check_type).
invalid_url	The provided URL is malformed or uses a disallowed scheme.
invalid_json	The request body is not valid JSON.
not_found	The requested resource (check, batch, monitor, key) does not exist.
invalid_api_key	The API key is invalid or has been revoked.
invalid_credentials	Authentication failed (JWT or API key).
insufficient_credits	Free tier exhausted and credit balance is too low for this check type.
rate_limited	Too many requests. Retry after the Retry-After period.
too_many_urls	Detect endpoint: more than 100 URLs provided.
too_many_batches	User has reached the limit of 3 active batches.
invalid_urls	No valid URLs found in the batch request after filtering.
monitor_limit_reached	User has reached the limit of 10 monitors.
cannot_revoke_current_key	Cannot revoke the API key being used for this request.
check_failed	The scanner encountered an error while checking the URL.
scanner_unavailable	The headless browser service is temporarily unavailable.
billing_unavailable	The payment service is temporarily unavailable.
batch_creation_failed	Failed to create the batch due to an internal error.
key_creation_failed	Failed to create the API key due to an internal error.
monitor_creation_failed	Failed to create the monitor due to an internal error.
internal_error	An unexpected internal error occurred.