Error Codes

DataBlue uses standard HTTP status codes. API-level errors return FastAPI's standard detail field. Scrape and job result payloads may also include success, error, and error_code fields when the request itself succeeds but the scrape job fails.

Code	Name	Description
400	Bad Request	Invalid request semantics, malformed IDs, unsupported options, or business-rule validation failures.
401	Unauthorized	Missing, invalid, or expired authentication token. Re-authenticate or generate a new API key.
403	Forbidden	Authenticated but blocked by permissions, account state, plan access, or email verification. Unverified accounts receive the X-Email-Verification-Required: true response header.
404	Not Found	The requested resource (job ID, monitor, schedule) does not exist.
429	Rate Limited	You exceeded a rate, operation, or credit limit. Retry timing is sent in the Retry-After response header when available.
422	Validation Error	Request body or query parameters failed schema validation. The detail field contains per-field validation errors.
500	Internal Error	Server-side error. This may indicate a bug or infrastructure issue. Retry with exponential backoff.
503	Service Unavailable	Endpoint is temporarily disabled or under maintenance. Data APIs may return this if a scraper is being updated.

Error Response Format

// 400 Bad Request
{
  "detail": "URL must start with http:// or https://"
}

// 401 Unauthorized
{
  "detail": "Could not validate credentials"
}

// 403 Email verification required
// Header: X-Email-Verification-Required: true
{
  "detail": "Email verification required. Verify your email before using DataBlue APIs."
}

// 422 Validation Error
{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "url"],
      "msg": "Field required",
      "input": {}
    }
  ]
}

// 429 Rate Limited
// Header: Retry-After: 60
{
  "detail": "Rate limit exceeded. Try again in a minute."
}

// Scrape job failure payload
{
  "success": false,
  "error": "Request timed out",
  "error_code": "TIMEOUT",
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}