Errors

Previous

All errors are JSON. Most responses follow a Problem Details-like shape with type, title, status, detail, and optional errors for validation issues.

Validation errors (422)

{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 422,
  "errors": {
    "email": ["This value is not a valid email address."],
    "password": ["This value should not be blank."]
  }
}

Domain errors (422/409)

Business rule violations return 422 with a short detail message. Example: {"detail":"invalid_monitor_status"}. Duplicate email registrations return 409 with detail: "email_already_used".

Authentication / authorization

  • 401: missing/invalid bearer token, invalid credentials, or login failures.
  • 403: forbidden (rare; used for access checks).

Example:

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid credentials"
}

Not found / method

  • 404: resource not found (e.g., a scrape that does not belong to the caller).
  • 405: wrong HTTP method.

Scrape gateway outcomes

POST /scrapes always returns a result envelope. HTTP codes reflect the outcome:

  • 200: ok: true (success)
  • 422: ok: false and status: "failed" (job finished with failure)
  • 504: timeout while waiting (errorCode: "timeout")
  • 502: upstream/gateway error (errorCode: "gateway_error")
Content Monitoring