Standard Error Response Envelope
All error responses return a structured JSON body with a descriptive detail or error message:
json
{
"success": false,
"status_code": 402,
"detail": "Insufficient credits. Required: 1, Available: 0",
"error_code": "INSUFFICIENT_CREDITS",
"documentation_url": "https://bouncelayer.com/docs/status-codes"
}Comprehensive HTTP Status Codes Table
| Status Code | Status Name | When It Is Returned | Credit Charged? |
|---|---|---|---|
| `200 OK` | Success | Request succeeded. A single email was verified, a bulk job was created/queried, or telemetry returned. | 1 Credit for valid, invalid, catch_all, or disposable; 0 Credits for indeterminate unknown |
| `400 Bad Request` | Bad Request | The request body could not be parsed as valid JSON, required parameters are missing, or the email address contains unparseable syntax. | 0 Credits (Free) |
| `401 Unauthorized` | Authentication Failed | Missing or invalid X-API-Key or Authorization: Bearer header, or the provided key has been revoked. | 0 Credits (Free) |
| `402 Payment Required` | Insufficient Balance | Your account has 0 credits remaining. Top up pay-as-you-go credits or upgrade your monthly subscription plan to resume API calls. | 0 Credits (Free) |
| `403 Forbidden` | Access Denied | The API key is valid but restricted from accessing this endpoint (e.g., read-only sub-key attempting a deletion). | 0 Credits (Free) |
| `404 Not Found` | Resource Missing | The requested resource (such as a job_id or webhook subscription ID) does not exist under your account. | 0 Credits (Free) |
| `409 Conflict` | Resource Conflict | Duplicate resource submission or a conflicting operation is currently in progress. | 0 Credits (Free) |
| `413 Payload Too Large` | Plan Cap Exceeded | The bulk verification job exceeds the batch limit for your current subscription plan (e.g. >10,000 on Free, >100,000 on Pro). | 0 Credits (Free) |
| `422 Unprocessable Entity` | Schema Validation Error | Parameter validation failed (e.g., negative timeout or invalid data type). | 0 Credits (Free) |
| `429 Too Many Requests` | Rate Limit Exceeded | Request velocity exceeded the concurrency or requests-per-minute threshold for your tier. Includes a Retry-After header. | 0 Credits (Free) |
| `500 Internal Server Error` | Engine Error | An unexpected server error occurred in our verification cluster. Our operations team is automatically alerted. | 0 Credits (Free) |
| `502 Bad Gateway` | Socket Gateway Timeout | Downstream SMTP proxy gateway failed to establish a raw TCP connection within the timeout window. | 0 Credits (Free) |
| `503 Service Unavailable` | Maintenance / Overload | Verification cluster or database is temporarily undergoing scheduled maintenance. | 0 Credits (Free) |
Rate Limiting & Concurrency
Rate limits apply per account and scale with your subscription tier:
| Plan Tier | Requests Per Minute (RPM) | Concurrent Bulk Batches | Max Batch Size |
|---|---|---|---|
| Free Developer | 60 RPM | 1 concurrent job | 1,000 emails |
| Starter ($12/mo) | 300 RPM | 3 concurrent jobs | 10,000 emails |
| Growth ($29/mo) | 600 RPM | 5 concurrent jobs | 25,000 emails |
| Pro ($79/mo) | 1,500 RPM | 10 concurrent jobs | 100,000 emails |
| Scale ($699/mo) | 3,000 RPM | 25 concurrent jobs | 500,000 emails |
Rate Limit Response Headers
http
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 1500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1729785660
Retry-After: 42