Errors

{
  "status": "error",
  "code": 409,
  "error_code": "DUPLICATE_REFERENCE",
  "message": "A payment with this reference already exists for this merchant...",
  "details": {
    "existing_transaction_id": "f5d238bd-f8ab-4379-9832-0f1ce6d65cbe",
    "existing_status": "pending",
    "reference": "ORDER_123"
  }
}

const res = await fetch("https://meet.briq.tz/api/v1/payments", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": idempotencyKey,
  },
  body: JSON.stringify(paymentRequest),
});
const body = await res.json();

if (body.status === "error") {
  switch (body.error_code) {
    case "PAYMENT_DECLINED":
    case "INSUFFICIENT_FUNDS":
      // Terminal for this attempt — ask the customer to try another method.
      // body.details.transaction_id stays queryable for reconciliation.
      break;
    case "DUPLICATE_REFERENCE":
      // Already have a live payment for this order — fetch it instead.
      // GET /api/v1/payments/{body.details.existing_transaction_id}
      break;
    case "PROVIDER_UNAVAILABLE":
    case "RATE_LIMIT_EXCEEDED":
      // Transient — retry with backoff, SAME Idempotency-Key.
      break;
    case "VALIDATION_ERROR":
      // body.details = [{field, message}] — surface to your form/logs.
      break;
    default:
      if (res.status === 401 || res.status === 403) {
        // Credentials or permissions — alert, don't retry.
      }
  }
}