Error Codes

All errors follow the envelope format with a SCREAMING_SNAKE_CASE code field.

Retry guidance

Every error also says, in machine-readable form, whether to retry, when, and what to change instead. The fields sit next to code and message on every error from API v1, API v2, check-windows, the CVE endpoints and authentication:

The existing code, message and detail are unchanged.

{
  "api": { "version": "1.0.0", "request_id": "bs-req-...", "timestamp": "2026-10-01T15:00:00Z" },
  "error": {
    "code": "BATCH_TOO_LARGE",
    "message": "At most 25 hosts per call. Split the hosts into batches of 25 or fewer and send one call per batch.",
    "retryable": false,
    "retry_after_seconds": null,
    "action": "reduce_batch",
    "max": 25,
    "detail": { "code": "BATCH_TOO_LARGE", "error": "batch_too_large", "message": "...", "max": 25, "received": 30 }
  }
}

Classification

Each host refused in data.rejected (API v2 and check-windows) carries retryable: false, retry_after_seconds: null and action: fix_input.

Cloudflare's own pages (for example its 524 timeout or its own 429) are outside BreachSpider and carry no guidance. Treat them by status: 429 and 5xx are retryable, everything else is not. The official Python SDK does this automatically.

Free API Trial Errors

Returned only for keys on the free API trial. Each carries detail.contact_url, the scoping email.

API v2 (Windows Patch Level) Errors

API v2 uses the same envelope. error.detail.error carries the specific code: insufficient_scope (403), environment_not_found (404), batch_too_large (413), rate_limited (429, with retry_after). Hosts refused by validation are listed per host in data.rejected with codes such as forbidden_field, placeholder_value and missing_field. See Windows Patch Level.

Tier Upgrade Response

When a feature is gated by tier, most endpoints return HTTP 403 with code FORBIDDEN and an upgrade_required detail block. For example, generating an API key on Free or Standard returns:

{
  "api": { "version": "1.0.0", "request_id": "bs-req-..." },
  "error": {
    "code": "FORBIDDEN",
    "message": "API access is available on the Professional tier and above.",
    "retryable": false,
    "retry_after_seconds": null,
    "action": "contact_us",
    "detail": {
      "error": "upgrade_required",
      "permission": "api_access",
      "current_tier": "standard",
      "upgrade_url": "/account/upgrade",
      "message": "API access is available on the Professional tier and above."
    }
  }
}

A small number of endpoints (audit log export, AI assistant chat) instead return HTTP 402 with code TIER_GATE. Handle both 402 and 403 as "upgrade required."

VALIDATION_ERROR Response

Validation errors include per-field detail:

{
  "api": { "version": "1.0.0", "request_id": "bs-req-..." },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "retryable": false,
    "retry_after_seconds": null,
    "action": "fix_input",
    "detail": [
      {
        "field": "query.severity",
        "message": "String should match pattern '^(CRITICAL|HIGH|MEDIUM|LOW)$'",
        "type": "string_pattern_mismatch"
      }
    ]
  }
}

Rate Limiting

When rate limited, wait error.retry_after_seconds (also the Retry-After header) and retry. The per-key limiter also keeps it in error.detail.retry_after. Without either, back off exponentially. A 429 with retryable: false (PARTNER_LIMIT, a used-up trial) will not clear by waiting seconds: see action.

{
  "api": { "version": "1.0.0", "request_id": "bs-req-..." },
  "error": {
    "code": "RATE_LIMITED",
    "message": "Per-key limit is 60 requests and 5000 hosts per minute.",
    "retryable": true,
    "retry_after_seconds": 36,
    "action": "retry_later",
    "detail": { "error": "rate_limited", "message": "Per-key limit is 60 requests and 5000 hosts per minute.", "retry_after": 36 }
  }
}

# Check your current rate limit status
curl -I -H "Authorization: Bearer bs_live_..." \
  "https://breachspider.com/api/v1/health"