Error Status Catalog & Wallet Rules

DataBee SiteAtlas API uses conventional HTTP status codes to indicate the success or failure of API requests.

---

HTTP Status Codes Summary

Status Code	Error Code	Description	Credit Action
400 Bad Request	MISSING_PARAMETER / INVALID_DOMAIN	Required parameter missing or domain format invalid	No charge
401 Unauthorized	UNAUTHORIZED	Invalid or missing API key header	No charge
402 Payment Required	INSUFFICIENT_CREDITS	Wallet balance is zero or insufficient	No charge
404 Not Found	NOT_FOUND	Endpoint route or resource not found	No charge
405 Method Not Allowed	METHOD_NOT_ALLOWED	HTTP verb not supported for this path	No charge
429 Too Many Requests	RATE_LIMIT_EXCEEDED	Exceeded maximum requests per second (RPS) limit	No charge
502 Bad Gateway	UPSTREAM_ERROR	Upstream provider connection failed	Automatically Refunded
504 Gateway Timeout	GATEWAY_TIMEOUT	Upstream request timed out	Automatically Refunded

---

Detailed Error Payload Examples

400 Bad Request

{
  "status": "error",
  "error": {
    "code": "MISSING_PARAMETER",
    "message": "The 'url' query parameter is required.",
    "status": 400
  }
}

401 Unauthorized

{
  "status": "error",
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key or missing Bearer token in Authorization header. Generate a free API key at https://console.databee.dev.",
    "status": 401
  }
}

402 Payment Required

{
  "status": "error",
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Your DataBee credit wallet has insufficient funds. Please top up at https://console.databee.dev.",
    "status": 402
  }
}

429 Too Many Requests

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Exceeded maximum allowed requests per second. Please retry after 1000ms.",
    "status": 429
  }
}

---

Credit Refund Guarantees

Automatic Refund Policy

If an API request fails with a 502 Bad Gateway or 504 Gateway Timeout, the DataBee Gateway automatically restores the deducted credit back to your account wallet instantaneously. No manual support ticket is required.