Error Codes

Use this page to understand common STOPBOT API error responses, HTTP status codes, and service-specific validation outcomes.

STOPBOT returns JSON for public API responses. Most request failures use an HTTP error status with status: failed or status: error. Detection results, blocked visitors, invalid emails, and invalid-but-parseable phone numbers are not always HTTP errors.

HTTP Status Codes

HTTP Status	Used For
200 OK	Request processed successfully. The result may still indicate a blocked visitor, invalid email, invalid phone number, or invalid SmartURLs keyname
204 No Content	Successful OPTIONS preflight response
400 Bad Request	Invalid API key format, invalid input format, invalid Blocker V2 configuration name, or unregistered Blocker V2 configuration
401 Unauthorized	API key was not found
402 Payment Required	API key quota is exceeded or the API key duration has expired
405 Method Not Allowed	Request method is not supported. Public service endpoints accept GET and OPTIONS
503 Service Unavailable	Temporary service, configuration, account, or lookup failure

Common Error Fields

Field	Description
status	Error status. Common values are failed and error
errorMessage	Human-readable error message
executionTime	Server-side execution time. Returned by most endpoint handlers
timeResponse	Response timestamp in YYYY-MM-DD HH:mm:ss format. Returned by most endpoint handlers

Authentication Errors

Invalid API Key Format

Returned when apikey does not match the required API key format.

HTTP status: 400 Bad Request

{
  "errorMessage": "Apikey format is invalid.",
  "status": "failed"
}

API Key Not Found

Returned when the API key format is valid, but the key does not exist.

HTTP status: 401 Unauthorized

{
  "status": "failed",
  "errorMessage": "API key not found. Please check your API key or create a new one."
}

Quota Or Expiration Error

Returned when the API key has no available quota or its active duration has expired.

HTTP status: 402 Payment Required

{
  "status": "failed",
  "errorMessage": "Please increase your quota or extend the duration of your API key."
}

Method Error

Method Not Allowed

Returned when a public service endpoint receives a method other than GET or OPTIONS.

HTTP status: 405 Method Not Allowed

{
  "errorMessage": "Method not allowed.",
  "status": "failed"
}

Service Errors

Configuration Load Failure

Returned when the service cannot load its runtime configuration.

HTTP status: 503 Service Unavailable

{
  "errorMessage": "Failed to load configuration, please wait until the issue is resolved.",
  "status": "failed"
}

Temporary Service Failure

Returned when the service cannot complete the request because a required backend operation is temporarily unavailable.

HTTP status: 503 Service Unavailable

{
  "status": "failed",
  "errorMessage": "Service temporarily unavailable. Please try again later or contact support at [e-mail]"
}

Account Detail Failure

Returned by Account when account details cannot be retrieved after authentication.

HTTP status: 503 Service Unavailable

{
  "status": "failed",
  "errorMessage": "Failed to retrieve account details."
}

IP Lookup Failure

Returned by IP Lookup when IP information cannot be resolved after validation.

HTTP status: 503 Service Unavailable

{
  "status": "failed",
  "errorMessage": "Failed to lookup IP information."
}

Input Validation Errors

Invalid IP Format

Returned by Blocker, Blocker V2, and IP Lookup when ip is not a valid IP address.

HTTP status: 400 Bad Request

{
  "errorMessage": "IP format is invalid.",
  "status": "failed"
}

SmartURLs uses an endpoint-specific invalid IP response:

HTTP status: 400 Bad Request

{
  "status": "error",
  "errorMessage": "Please enter a valid IP FORMAT."
}

Invalid Blocker V2 Configuration Name

Returned when confname does not match the accepted Blocker V2 configuration name format.

HTTP status: 400 Bad Request

{
  "errorMessage": "Please enter a valid Configuration Name.",
  "status": "failed"
}

Blocker V2 Configuration Not Registered

Returned when confname is valid in format, but is not registered for the authenticated account.

HTTP status: 400 Bad Request

{
  "errorMessage": "Your Configuration Name is not registered in our database.",
  "status": "failed"
}

Invalid Phone Number Format

Returned by Phone Number Identify when number does not match the accepted phone number format.

HTTP status: 400 Bad Request

{
  "status": "error",
  "errorMessage": "Please enter a valid number. (ex: [phone])"
}

Successful Requests With Negative Results

These responses are not HTTP errors. The API successfully processed the request, but the service result is negative or blocked.

SmartURLs Invalid Keyname

Invalid, unknown, inactive, or unowned SmartURLs keynames can return 200 OK with a blocked decision.

{
  "isBot": 1,
  "blockAccess": 1,
  "detectActivity": "BLOCK BY INVALID KEYNAME",
  "status": "success"
}

Email Validation Invalid Format

Email Validation returns 200 OK with isEmail: false when the submitted email does not match the accepted email format.

{
  "isEmail": false,
  "status": "success"
}

Phone Number Not Valid

Phone Number Identify returns 200 OK with isValid: false when the submitted number passes the basic format check but cannot be validated as a real phone number.

{
  "isValid": false,
  "status": "success"
}

Visitor Blocked By Detection

Blocker, Blocker V2, and SmartURLs can return 200 OK even when the visitor should be blocked. Use the service-specific decision fields instead of treating only HTTP errors as blocked traffic.

Service	Decision Field
Blocker	blockAccess
SmartURLs	blockAccess
Blocker V2	status.block

V1 Difference

Legacy V1 often returned HTTP 200 OK with:

{
  "status": "error",
  "message": "..."
}

For V2 integrations, use the HTTP status code together with the JSON status, apiStatus, and service-specific decision fields.