Skip to main content

Errors and Retries

Error response shape​

All API errors follow this format:

{
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE",
  "details": null
}
ScenarioRetry?Guidance
Network timeout / connection issueYesRetry with same idempotency-key
HTTP 5xxYesExponential backoff + same idempotency key
HTTP 429YesBackoff and retry
HTTP 4xx validation/auth errorsNoFix request first
HMAC_INVALIDNoFix signing implementation

Frequently seen codes​

Security and auth​

  • API_KEY_MISSING
  • API_KEY_INVALID
  • HMAC_MISSING
  • HMAC_INVALID
  • IDEMPOTENCY_KEY_MISSING

Domain validation​

  • PARTNER_NOT_FOUND
  • PARTNER_NOT_ACTIVE
  • KYC_NOT_APPROVED
  • CLIENT_NOT_FOUND
  • CLIENT_NOT_ACTIVE
  • TX_NOT_FOUND

Webhook​

  • STRIPE_SIGNATURE_MISSING
  • STRIPE_SIGNATURE_INVALID
  • INVALID_WEBHOOK_JSON
  • PAYMENT_INTENT_NOT_FOUND

Settlements and payouts​

  • BATCH_NOT_FOUND
  • BATCH_ALREADY_PAID
  • PAYOUT_FAILED

Idempotency replay example​

{
  "clive_tx_id": "CLVTX_1739378102312_420",
  "status": "initialized",
  "idempotentReplay": true
}

If you get this on retry, treat it as success for the original attempt.