Skip to content

Error Codes

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

Code HTTP Status Meaning
AUTH_REQUIRED 401 Valid session cookie or API key required
TIER_GATE 402 Feature requires a higher subscription tier
FORBIDDEN 403 Authenticated but not authorized for this resource
viewer_role 403 Read-only (viewer) member attempted a write operation
NOT_FOUND 404 Resource does not exist
METHOD_NOT_ALLOWED 405 HTTP method not supported on this endpoint
VALIDATION_ERROR 422 Request parameters failed validation
RATE_LIMITED 429 Too many requests - back off and retry
INTERNAL_ERROR 500 Server error - our team has been notified

TIER_GATE Response

When a feature is gated by tier, the response includes upgrade information:

{
  "api": { "version": "1.0.0", "request_id": "bs-req-..." },
  "error": {
    "code": "TIER_GATE",
    "message": "This feature requires professional tier or above.",
    "detail": {
      "feature": "api_keys",
      "required_tier": "professional",
      "upgrade_url": "https://breachspider.com/upgrade"
    }
  }
}

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.",
    "detail": [
      {
        "field": "body.severity",
        "message": "value is not a valid enumeration member",
        "type": "type_error.enum"
      }
    ]
  }
}

Rate Limiting

When rate limited, back off exponentially and retry. The Retry-After header indicates seconds to wait.

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