> ## Documentation Index
> Fetch the complete documentation index at: https://developers.perkstar.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and request tracing

> Handle Perkstar API failures consistently and give support enough detail to trace them.

API errors use one predictable envelope:

```json theme={null}
{
  "error": {
    "type": "validation_error",
    "code": "invalid_request_body",
    "message": "The request body is invalid.",
    "param": "transaction.type"
  }
}
```

## Status codes

| Status | Meaning |
| - | - |
| `400` | Malformed JSON or invalid request shape |
| `401` | Missing, invalid, expired, or revoked credential |
| `403` | The key lacks a scope, plan access, or live-write permission |
| `404` | The requested record does not exist in this business |
| `409` | The request conflicts with existing data or idempotency state |
| `410` | The key or business has been permanently closed or revoked |
| `422` | The request is valid JSON but incompatible with the card or balance |
| `429` | The key exceeded its rate limit |
| `5xx` | Perkstar could not complete an otherwise valid request |

## Universal response headers

Every success and error includes:

* `X-Request-Id`: the exact request reference for logs and support.
* `X-API-Version`: the date-versioned contract served by the endpoint.
* `X-RateLimit-Limit`: the credential's current per-minute allowance.
* `X-RateLimit-Remaining`: calls left in the current window.
* `X-RateLimit-Reset`: Unix seconds when the window resets.
* `Retry-After`: seconds to wait after a `429`.

Log the request ID, endpoint, status, error code, and your own operation ID. Do
not log bearer credentials, full customer payloads, or webhook secrets.

## Unknown outcomes

If the connection drops after a POST, treat the result as unknown rather than
failed. Retry with the same `Idempotency-Key`. For POS transactions, send the
same `external_transaction_id` as well.

`400 reserved_external_transaction_id` means the identifier used a namespace
owned by a managed POS integration. Choose a stable prefix belonging to your
app and retry with a new identifier.

## Contacting support

Email [support@perkstar.co.uk](mailto:support@perkstar.co.uk) with:

1. `X-Request-Id`;
2. UTC timestamp;
3. HTTP method and path;
4. response status and error code; and
5. the first 12-character key prefix shown in the dashboard.

Never include the full API key or personal customer data.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.