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

# Responses and errors

> Two response shapes, and what each status code means.

Each endpoint page includes its response schemas and status codes.

## Success envelope

Every `2xx` response uses this shape:

```json theme={"dark"}
{
  "status": true,
  "message": "OK",
  "data": {}
}
```

The shape of `data` depends on the endpoint. Check `status` as well as the HTTP code: the published schema permits `status: false` when an operation returns a negative result without throwing.

## Nullable response fields

Optional fields may be omitted. Nullable fields may be returned as `null`; these are separate properties of the contract. For example, a customer without an email address can return `"email": null`. The OpenAPI 3.1 schemas explicitly include `null` where it is allowed. Required non-null fields and non-null array items remain non-null.

A single-resource GET for a missing or deleted resource returns HTTP `404` with the error envelope below, rather than a successful empty resource.

## Error envelope

```json theme={"dark"}
{
  "status": false,
  "error": "INVALID_REQUEST",
  "message": "..."
}
```

Use the machine-readable `error` code when handling failures. The `message` provides context for a person investigating the request.

| HTTP status | Meaning                                                           |
| ----------- | ----------------------------------------------------------------- |
| `400`       | Invalid request shape or validation error                         |
| `401`       | Credential authentication failed                                  |
| `403`       | Required scope or actor permission is missing                     |
| `404`       | Resource or endpoint was not found                                |
| `409`       | Conflict, including idempotency-key reuse or an in-flight request |
| `413`       | Request body exceeds the published size limit                     |
| `429`       | Rate limited; wait for the `Retry-After` delay                    |
| `500`       | Unexpected server error                                           |

## Retries

Correct validation and permission errors before retrying. For `429`, follow [Rate limits](/api/rate-limits). For a timeout or server error, use backoff and retain the same [idempotency key](/api/idempotency) for a write. Check the resource if the outcome remains uncertain.