> ## 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.

## 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.


## Related topics

- [TypeScript SDK](/sdks/typescript.md)
- [Idempotency and retries](/fundamentals/idempotency.md)
- [Python SDK](/sdks/python.md)
- [Create or upsert a customer](/api-reference/customers/create-or-upsert-a-customer.md)
- [Postman collection](/tools/postman.md)