Errors
Every error response has the same simple shape.
Every error response looks like this:
{
"code": "invalid_refund_amount",
"detail": "refundedAmount must be greater than 0 and at most disputeAmount.",
"param": "refundedAmount",
"request_id": "req_8mP4xV2qLnK7vQjF"
}| Field | Notes |
|---|---|
code | Stable, machine-readable. Switch on this — never on detail. |
detail | Human-readable explanation. Wording may change; don't parse it. |
param | Optional. The field or query param that failed validation. |
request_id | Always present. Include it when contacting support — it pins your exact request in our logs. |
request_id is also returned as the X-Request-Id header on every
response, success or failure.
Status codes
| Status | When |
|---|---|
| 200 | Success. |
| 400 | Request malformed or failed validation. |
| 401 | Missing or invalid API key. |
| 403 | Valid key, but missing the required permission. |
| 404 | Not found or not yours — we don't distinguish, to prevent ID guessing. |
| 409 | Conflict — e.g. resolving an already-declined alert, or an idempotency key reuse mismatch. |
| 422 | Well-formed but rejected — e.g. resolving past the respondBy window. |
| 500 | Disputely bug. Retry with the same Idempotency-Key. |
| 502 | Card network issue. Retry with backoff and the same Idempotency-Key. |
Common codes
code | Status | Meaning |
|---|---|---|
missing_credentials | 401 | No Authorization header. |
invalid_credentials | 401 | Key not recognized or revoked. |
ip_not_allowed | 401 | Request IP is outside the key's allowlist. |
insufficient_scope | 403 | Key lacks the required permission. |
alert_not_found | 404 | Alert doesn't exist or isn't yours. |
account_not_found | 404 | accountId param doesn't match your account. |
invalid_request | 400 | Body or query params failed validation — check param. |
invalid_refund_amount | 400 | Refund is ≤ 0 or exceeds disputeAmount. |
currency_mismatch | 400 | refundedCurrency ≠ disputeCurrency. |
invalid_cursor | 400 | Pagination cursor malformed or expired. Restart from page 1. |
alert_not_actionable | 409 | RDR alert, or already declined. |
idempotency_conflict | 409 | Same Idempotency-Key, different body. Pick a new key. |
cannot_resolve_after_window | 422 | Past the alert's respondBy deadline. |
provider_unavailable | 502 | Card network timed out. Retry with the same key. |
provider_rejected | 502 | Card network rejected the action — see detail. |
internal_error | 500 | Disputely-side. Retry with the same key. |
New codes may be added over time — make sure unknown codes fall through to a sensible default branch in your handler.