Errors

The API reports failures on two levels. Problems with authentication are HTTP errors. Everything that happens while an operation runs is reported in the errors array of a normal GraphQL response.

HTTP status codes

Status	Meaning	What to do
`200`	The request was processed. It can still contain errors, see below.	Check `errors` in the body.
`401`	The token is missing, malformed or expired.	Request a new token and retry once. If it fails again, check the API key.
`502`, `503`, `504`	HuskyCare is temporarily unavailable.	Retry later with increasing delays.
other `5xx`	Unexpected server error.	Retry a query later. For a mutation, check whether it took effect before you retry.

Errors in the response body

A response with errors has an errors array. data is null, or contains the parts of the result that did succeed:

{
  "errors": [
    {
      "message": "Authorization denied: missing features: client:core:edit",
      "path": ["createClient"],
      "extensions": {
        "error": {
          "errorCode": "AUTHORIZATION_DENIED_MISSING_FEATURES",
          "missingFeatures": ["client:core:edit"]
        }
      }
    }
  ],
  "data": null
}

Read extensions.error.errorCode to decide how to handle an error. It is a value of the ErrorCode enum, and the API reference describes each code. The top-level message is meant for logs. Its wording can change at any time and it can contain IDs, so don't parse it or show it to end users.

Business errors

Most error codes report that a request breaks a business rule, for example an absence that overlaps an existing one:

{
  "extensions": {
    "error": {
      "errorCode": "ABSENCES_OVERLAP",
      "message": "Absence overlaps an existing absence",
      "params": {
        "otherAbsentFrom": "2026-06-01",
        "otherAbsentTo": "2026-06-14"
      }
    }
  }
}

errorCode identifies the rule. Show your users a message of your own for it.
params holds the values your message can include. The description of each code in ErrorCode lists its parameters. Values are unformatted: dates in ISO 8601, amounts as plain decimals. params is left out when a code has none.
message is a technical text for logs, like the top-level message.

Retrying the same request returns the same error. Correct the input first.

Missing permissions

AUTHORIZATION_DENIED_MISSING_FEATURES means the token is valid, but the user or API key lacks a feature the operation requires. extensions.error.missingFeatures lists the missing features. Give the API key a role template that contains them. See Authentication.

Errors without an error code

An error without extensions.error has one of two causes:

The request does not match the schema, for example a misspelled field or a missing required argument. Fix the query. The API Playground highlights these errors as you type.
An unexpected error in HuskyCare. Handle it like an HTTP 5xx.

Checklist for your client

Treat a response as successful only if it has no errors array.
Handle 401 by requesting a new token.
Map the error codes that matter for your integration to your own messages, and log the rest with their path.
Retry only on 5xx and network errors, and only when repeating the request is safe.

HTTP status codes​

Errors in the response body​

Business errors​

Missing permissions​

Errors without an error code​