Errors

Destiny uses conventional HTTP status codes. A 2xx indicates success; other codes indicate a problem, with detail carried in the warnings and warn_fields keys of the response body.

Status codes seen in the API

Code	Meaning
200 OK	The request succeeded.
400 Bad Request	The request was malformed or could not be processed.
401 Unauthorized	Authentication failed (e.g. wrong password) or the token is missing/invalid.
422 Unprocessable Entity	The request was well-formed but a business rule rejected it.
425 Too Early	The requested precondition was not yet met (e.g. unknown username during reset).

Error body shapes

General problems — warnings

{
  "warnings": [
    "Cannot assign unit as primary, a unit is already allocated in that slot."
  ]
}

Field-level validation — warn_fields

Each entry maps a field name to a human-readable message:

{
  "warn_fields": [
    {
      "password": "An incorrect password was provided for the username: demo."
    }
  ]
}

Handling errors

A resilient client should:

1. Branch on the HTTP status code first.
2. On a non-2xx, read warnings for general messages and warn_fields for per-field validation errors.
3. Surface warn_fields messages next to the corresponding form inputs where relevant.

tip

For requests scoped to the partner / agency / client hierarchy, you can call the permission-check endpoint before acting to avoid predictable 401/422 responses. See Authentication → Permission checks.