> For the complete documentation index, see [llms.txt](https://docs.stopbot.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stopbot.net/v2/api-v2-documentation/error-codes.md).

# Error Codes

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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "status": "failed",
  "errorMessage": "Service temporarily unavailable. Please try again later or contact support at admin@stopbot.com"
}
```

#### Account Detail Failure

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

HTTP status: `503 Service Unavailable`

```json
{
  "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`

```json
{
  "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`

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

SmartURLs uses an endpoint-specific invalid IP response:

HTTP status: `400 Bad Request`

```json
{
  "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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "status": "error",
  "errorMessage": "Please enter a valid number. (ex: +11231231234)"
}
```

### 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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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:

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

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