Errors and request tracing

API errors use one predictable envelope:

{
  "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 with:

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

Never include the full API key or personal customer data.

Get started

Core concepts

Integration recipes

Ship safely

Status codes

Universal response headers

Unknown outcomes

Contacting support

​Status codes

​Universal response headers

​Unknown outcomes

​Contacting support

Status codes

Universal response headers

Unknown outcomes

Contacting support