Errors

Handle API errors gracefully

Error Format

All error responses follow a consistent structure:

{
  "data": null,
  "errors": [
    {
      "message": "Missing required field: name",
      "layer": "product"
    }
  ]
}

Reading the Errors Array

The errors array is ordered from root cause to top-level caller:

• errors[0] — the root cause of the failure (most useful for debugging)
• errors[n] — the top-level caller that surfaced the error

In most cases, you only need to inspect errors[0].message for the actionable error description.

---

HTTP Status Codes

Code	Meaning	Description
200	Success	Request processed successfully
400	Bad Request	Invalid parameters or malformed request body
401	Unauthorized	Missing or invalid authentication credentials
403	Forbidden	Valid credentials but insufficient permissions
404	Not Found	Requested resource does not exist
409	Conflict	Idempotent request is already being processed
429	Rate Limited	Too many requests in a short period
500	Server Error	Internal server error
501	Not Implemented	Requested feature is not yet available
502	Bad Gateway	Upstream service error

---

Error layer Field

Each error includes a layer string indicating which part of the system produced the error. Use the layer value alongside message to identify the root cause when debugging.

---

Common Error Scenarios

Authentication Errors (401)

{
  "data": null,
  "errors": [
    {
      "message": "Token has expired",
      "layer": "user"
    }
  ]
}

Solutions:

• Verify your Merchant ID and private key are correct
• Ensure the SDK is initialized with valid credentials
• Check that your private key matches the registered public key

Validation Errors (400)

{
  "data": null,
  "errors": [
    {
      "message": "Store name must be between 1 and 100 characters",
      "layer": "store"
    }
  ]
}

Solutions:

• Check required fields are present
• Verify field value formats and constraints
• Ensure amounts are display format strings (e.g., “29.00”)

Permission Errors (403)

{
  "data": null,
  "errors": [
    {
      "message": "Only store owner can delete store",
      "layer": "store"
    }
  ]
}

Solutions:

• Verify the API Key has the required permissions
• Ensure the user belongs to the correct store

Idempotency Conflicts (409)

{
  "data": null,
  "errors": [
    {
      "message": "Request with this idempotency key is already being processed",
      "layer": "gateway"
    }
  ]
}

Solutions:

• Wait for the original request to complete
• Use a different X-Idempotency-Key for a new request

---

Handling Errors in Code

TypeScript SDK

import { WaffoPancake, WaffoPancakeError } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});

try {
  const { store } = await client.stores.create({ name: "My Store" });
} catch (err) {
  if (err instanceof WaffoPancakeError) {
    const rootCause = err.errors[0];
    console.error(`Error [${rootCause.layer}]: ${rootCause.message}`);
    // err.status contains the HTTP status code
  }
}

---

Retry Strategy

Retry these status codes with exponential backoff:

• 429 — Rate limited (respect Retry-After header if present)
• 500 — Internal server error
• 502 — Bad gateway

async function retryRequest(fn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      const status = error.status;
      if (![429, 500, 502].includes(status) || attempt === maxRetries - 1) {
        throw error;
      }
      const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

Do not retry 400, 401, 403, or 404 errors. These indicate issues that must be fixed in the request itself.

---

Idempotency for Safe Retries

Use the X-Idempotency-Key header to safely retry write operations without creating duplicates:

curl -X POST https://api.waffo.ai/v1/actions/checkout/create-session \
  -H "Content-Type: application/json" \
  -H "X-Store-Slug: your-store-slug" \
  -H "X-Environment: test" \
  -H "X-Idempotency-Key: MER_2aUyqjCzEIiEcYMKj7TZtw-8f14e45f-ea8c-4b0a-9f7d-3b2c1d0e5a67" \
  -d '{"productId": "...", "productType": "onetime", "currency": "USD"}'

• Idempotency keys are cached for 24 hours
• Sending the same key returns the cached response
• If the original request is still processing, returns 409 Conflict

Idempotency Key Requirements

Requirement	Specification
Uniqueness	Globally unique per request within your merchant account
Max length	256 characters
Allowed chars	Letters, numbers, hyphens (-), underscores (_)

The key is the entire cache identity of the request, so uniqueness is the requirement to plan for. Two options:

1. Let the SDK generate it (preferred). The TypeScript SDK derives the key as a deterministic hash of merchantId + path + body, which is unique per request by construction.
2. Build it yourself. Embed your merchantId and a high-entropy component such as a UUID, e.g. MER_2aUyqjCzEIiEcYMKj7TZtw-8f14e45f-ea8c-4b0a-9f7d-3b2c1d0e5a67.

A short, guessable key such as order-abc-123 can match a key already used by a different request. In that case the response you receive is that request’s cached response, not a result for your own call.