Errors and limits

Errors follow RFC 7807: type, title, status, detail and a stable code. The rate limit is 100 requests a minute for each key, reported in the rate-limit headers.

• 400 — the request body could not be read
• 401 — missing or revoked key
• 403 — the key lacks the scope for this call
• 404 — no such card, customer or reward in this business
• 409 — the idempotency key was used with a different body
• 422 — a program rule rejected the write, for example a stamp cooldown
• 429 — over the rate limit; retry after the header says so

Stable codes worth handling on your side:

• customer_blocked — the business blocked this customer: no new cards, no scans
• test_mode_live_card — a sk_test_ key tried to change a live card; use a live key
• business_suspended — the business is suspended; the API answers 403 until it is restored
• insufficient_units — a prepaid use asked for more units than the card holds
• insufficient_balance — an undo or redeem would take the balance below zero

A customer who removes a card and joins the same program again gets a new card without welcome points; a used coupon stays used.

Example

curl https://perfito.al/v1/cards/PF-8F2A-19 \
  -H "Authorization: Bearer sk_test_…"

$ch = curl_init('https://perfito.al/v1/cards/PF-8F2A-19');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $key, 'Content-Type: application/json'],
]);
$data = json_decode(curl_exec($ch), true);

const res = await fetch('https://perfito.al/v1/cards/PF-8F2A-19', {
  method: 'GET',
  headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' },
});
const data = await res.json();