> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowpayroll.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Response format

> Every Flow Payroll response uses the same envelope, so you can parse success and error responses with one shared model.

All API responses follow a consistent structure, giving you predictable parsing across every endpoint.

## Success

```json theme={null}
{
  "message": {
    "text": "Operation completed successfully",
    "token": "operationCompletedSuccessfully"
  },
  "content": {
    "data": { },
    "metadata": {
      "dateFormat": "yyyy-MM-dd",
      "dateTimeFormat": "yyyy-MM-dd'T'HH:mm:ss.fffZ"
    }
  }
}
```

* **`message.text`** — a human-readable summary.
* **`message.token`** — a stable machine-readable key. Branch on this rather than on `message.text`, which may change wording or be localised.
* **`content.data`** — the resource(s) returned by the endpoint.
* **`content.metadata`** — context such as the date and date-time formats used in `data`.

## Errors

Errors use the same envelope. The `token` identifies the error, and `tokenArguments` carries any parameters needed to render a message.

```json theme={null}
{
  "message": {
    "text": "Operation failed",
    "token": "operationFailed",
    "tokenArguments": [
      {
        "name": "argumentName",
        "value": "argumentValue"
      }
    ]
  }
}
```

<Tip>
  Always key your handling off `message.token`. It is stable across releases and localisations, whereas `message.text` is presentation only.
</Tip>

## HTTP status codes

| Status        | Meaning                                                                                  |
| ------------- | ---------------------------------------------------------------------------------------- |
| `200` / `201` | Success.                                                                                 |
| `400`         | Validation error — check `message.token` and `tokenArguments`.                           |
| `401`         | Missing or invalid `X-Auth-Token` — see [Authentication](/api-reference/authentication). |
| `403`         | Authenticated but not authorised for the resource.                                       |
| `404`         | Resource not found within your organisation.                                             |
| `429`         | Rate limited — back off and retry.                                                       |
| `5xx`         | Server error — retry with backoff; if it persists, contact support.                      |