Errors
The API answers with standard HTTP status codes. Anything other than 2xx carries a JSON body, except authentication and idempotency failures, which are plain text (see Authentication).
{
"code": 3,
"message": "customer_uuid is required",
"details": []
}
message is written for your logs. code is the gRPC status code the API maps to the HTTP status, useful when one HTTP status covers several causes. details is empty today and is safe to ignore.
Status codes
| Status | Meaning | What to do |
|---|---|---|
400 |
The request is malformed or breaks a rule: a missing field, a bad identifier, a selection that cannot be acted on. code is 3 for invalid input and 9 for a precondition that does not hold. |
Fix the request. Retrying unchanged returns the same answer. |
401 |
The credential is missing, malformed or wrong. Plain-text body. | Check the header and the environment. See Authentication. |
403 |
The credential is valid but may not do this. | Contact Casap. |
404 |
No such dispute, customer or account for your organization. | Check the identifier and the environment. |
409 |
A request with the same idempotency key is still running. | Wait, then retry with the same key. |
429 |
A system behind the request is throttling. | Back off and retry. Honour Retry-After when present. |
500 |
Casap failed. The request may or may not have taken effect. | Retry with the same idempotency key, then contact Casap if it persists. |
503 |
A dependency was unavailable. | Retry with backoff. |
Eligibility errors
The Eligibility Check returns 200 with eligible: false and one error per failed rule, so you can show the member what to change. Branch on scope first.
Transaction-scoped errors name the offending transactions in transactionIds; the member can adjust the selection and stay in the flow.
RAIL_MISMATCH: the selection mixes payment rails. Pick one rail.CARD_MISMATCH: the selection spans more than one card. Pick one card.TRANSACTION_NOT_FOUND: an id matches no transaction on the account. Refresh with List Disputable Transactions.TRANSACTION_NOT_DISPUTABLE: the transaction's type is excluded by your organization's rules. Direct the member to support.TRANSACTION_NOT_SETTLED: not settled yet. Retry after settlement.TRANSACTION_ALREADY_DISPUTED: already part of an open dispute. Point the member to it.TRANSACTION_OUTSIDE_ELIGIBILITY_WINDOW: older than your organization's window for online disputes. Direct the member to support.
Member-scoped errors leave transactionIds empty; no selection change helps.
MEMBER_INELIGIBLE: the member cannot file right now. Direct the member to support.
Treat any code you do not recognise as "cannot dispute right now". TRANSACTION_INELIGIBLE is retired and never returned.
Idempotency
Create Dispute accepts an X-Idempotency-Key header, up to 255 bytes, enabled for your organization at onboarding. Send a fresh key per intended dispute and reuse it on every retry of that same request: a retry that arrives while the first attempt is still running gets 409, and a retry within 24 hours of it finishing gets the stored response instead of a second dispute. A different body under a key you already used is not deduplicated, so never recycle keys. Without the header, or for an organization that has not enabled idempotency, every request is treated as new.
Retrying
Retry 429, 500 and 503 with exponential backoff, starting around one second and capping at a minute. Never retry 400, 401, 403 or 404 without changing the request.