Status: Stable error envelope.
Note: Specific business errors may expand over time, but existing codes should remain additive in v1.

Errors

Standard envelope

All platform API errors use this shape:

{
  "ok": false,
  "error": {
    "code": "invalid_signature",
    "message": "Request signature could not be verified",
    "retryable": false
  }
}

Optional details may be present:

{
  "ok": false,
  "error": {
    "code": "duplicate_idempotency_conflict",
    "message": "Idempotency key was reused with a different payload.",
    "retryable": false,
    "details": {
      "idempotencyKey": "settle-txn-abc123"
    }
  }
}

Common auth-layer codes

• unauthorized
• invalid_signature
• stale_timestamp
• invalid_request

Examples include:

• missing or inactive credential
• wrong key for the API environment
• clubId supplied and not matching the authenticated club key
• malformed timestamp or signature header

Common business-layer codes

• cardholder_not_found
• partner_not_found
• redemption_not_found
• unsupported_currency
• partner_configuration_incomplete
• partner_funding_restricted
• insufficient_partner_points_pool
• insufficient_points_balance
• insufficient_partner_cash_capacity
• missing_payout_reference
• duplicate_idempotency_conflict
• duplicate_event
• external_transaction_conflict
• external_request_conflict
• invalid_transaction_amount
• points_calculation_zero
• original_earn_not_found
• invalid_original_earn
• already_reversed
• manual_review_required
• invalid_redemption_points
• invalid_redemption_value
• minimum_redemption

Endpoint-specific notes

Member create/update

• partner_not_found: the resolved club record no longer exists.
• invalid_request: the member payload is missing required fields or contains invalid email data.

Settled transactions

• invalid_transaction_amount: transaction.amountMinor must be greater than zero.
• points_calculation_zero: the configured earn rate and transaction amount produced no points.
• external_transaction_conflict: the same externalTransactionId was used with a different payload.

Reversals

• original_earn_not_found: no settled earn award exists for the supplied externalTransactionId.
• already_reversed: the settled earn has already been reversed.
• manual_review_required: the original points are no longer fully available to reverse.

Redemptions

• minimum_redemption: the calculated cash value is below the platform minimum.
• missing_payout_reference: the member does not yet have payout details ready.
• insufficient_partner_cash_capacity: the club does not have enough available funded cash capacity.

Typical HTTP mapping

• 400 malformed request or path/header issues
• 401 auth or signature failures
• 404 member or redemption not found
• 409 duplicate/conflict state
• 422 business-rule validation failure

Retry guidance

Safe to retry:

• same POST with same body and same idempotency key after a transient transport failure

Do not retry without fixing input:

• signature errors
• currency mismatch
• missing payout reference
• insufficient points
• club configuration errors

Escalate for ops review:

• manual_review_required
• repeated payout failures after reservation