Responses and errors

Successful calls return the endpoint response directly as JSON.

{
  "success": true,
  "merchant": "Example Coffee"
}

Errors use a consistent JSON shape:

{
  "code": 401,
  "message": "Invalid API key"
}

Common status codes

Status	Meaning
200	The request succeeded.
400	A required field is missing or invalid.
401	The API key is missing or invalid.
403	The API key lacks the endpoint's required scope.
404	The merchant, integration, or reward was not found.
409	An idempotency key conflicts or is still processing.
429	A rate or concurrency limit was exceeded.
500	An unexpected server error occurred.

Do not retry 400, 401, 403, or 404 responses without correcting the request, credentials, scopes, or resource identifier. For an idempotency-related 409, honour Retry-After and retry the exact same request. Retry transient 500 responses with exponential backoff and jitter.