API error codes

Hosted API errors return a legacy error string for backward compatibility and an additive error_v2 object with machine-readable codes, a request id, and documentation links.

Response shape

{
  "error": "Watch not found",
  "error_v2": {
    "code": "not_found",
    "message": "Watch not found",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "docs_url": "https://developers.driftguard.org/docs/errors#not_found"
  }
}

Every error response includes an X-Request-Id header matching error_v2.request_id. Include this id when contacting support.

Error codes

Code	HTTP	Meaning
`unauthorized`	401	Missing or invalid API key / trial session.
`payment_required`	402	Feature requires Pro or Team plan.
`validation_failed`	400	Invalid request body or query parameters.
`not_found`	404	Resource does not exist or is not visible to your account.
`rate_limited`	429	Too many requests — retry after the `Retry-After` header.
`conflict`	409	State conflict (duplicate or concurrent update).
`internal`	5xx	Unexpected server error — retry with the same request id.

Rollout

error_v2 is live on watches, drift, and command-center API families. Remaining routes continue to return the legacy error string until migrated.