{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"ParadisePay Docs","description":"ParadisePay is the groundbreaking payment gateway that lets you integrate with the future of payments."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"api-response-codes","__idx":0},"children":["API response codes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two different things can come back from a payment that did not go through, and"," ","they need opposite handling."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["error"]}," means the request failed. You get a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4xx"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5xx"]}," and an error"," ","body. No transaction was created."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["decline"]}," means the request succeeded and the issuer said no. You get a"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," and a transaction whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This page covers both, errors first."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-error-envelope","__idx":1},"children":["The error envelope"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every error, from every endpoint, has the same four fields."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"error_code\": \"INVALID_REQUEST_DATA\",\n  \"error_message\": \"The API request contains invalid data.\",\n  \"details\": {\n    \"amount\": \"Invalid amount\",\n    \"payment_method.pan\": \"Malformed PAN\"\n  },\n  \"source\": {\n    \"system\": \"TSYS\",\n    \"code\": \"13\",\n    \"message\": \"Invalid amount\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Purpose"},"children":["Purpose"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The stable code. Branch on this"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_message"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The same thing in words, for a log. May be reworded; do not match on it"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Field-level specifics, as a flat map of field name to problem. May be null"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The processor's own system, code, and message, passed through unchanged. May be null"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two rules govern it:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Specifics live in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details"]},", never in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_message"]},"."]}," That keeps the code"," ","list small and the messages stable."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source"]}," is the processor, not us."]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["system"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TSYS"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VERICHECK"]},". It is"," ","there for your support and reconciliation, not for your control flow — you"," ","branch on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_code"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-codes","__idx":2},"children":["The codes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Thirteen codes can reach you today."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"something-is-wrong-with-the-request","__idx":3},"children":["Something is wrong with the request"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"HTTP"},"children":["HTTP"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"error_code"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_code"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What happened"},"children":["What happened"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Retry"},"children":["Retry"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_REQUEST_DATA"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A field is present and its value is unusable"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["After fixing the value"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REQUIRED_DATA_MISSING"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A required field is absent"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["After supplying it"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_ACTION"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The request is well formed, but the operation does not apply to this transaction's state"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AMOUNT_LIMIT_EXCEEDED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A single amount is outside the allowed range"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VELOCITY_LIMIT_EXCEEDED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A count or value cap over a period is spent"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Later"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_ACTION"]}," is the one to read carefully. It does not mean the request was"," ","malformed; it means the thing you asked for does not make sense for that"," ","transaction right now — capturing a sale, refunding something unsettled,"," ","canceling something already canceled. The section below lists the common ones."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"you-are-not-allowed","__idx":4},"children":["You are not allowed"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"HTTP"},"children":["HTTP"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"error_code"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_code"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What happened"},"children":["What happened"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Retry"},"children":["Retry"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["401"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NOT_AUTHENTICATED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Api-Key"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Client-Id"]}," is missing or wrong"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["403"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UNAUTHORIZED_ACTION"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authenticated, but not permitted to do this"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["404"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RESOURCE_NOT_FOUND"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No such URL, or no such resource ID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["409"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DUPLICATE_ACTION"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The gateway or the processor has already seen this"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," does not distinguish a missing header from a wrong key. Check that"," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["both"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Api-Key"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Client-Id"]}," are present before assuming the key is bad —"," ","see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/get-started/authentication"},"children":["Authentication"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"something-failed-on-our-side-or-the-processors","__idx":5},"children":["Something failed on our side or the processor's"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"HTTP"},"children":["HTTP"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"error_code"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_code"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What happened"},"children":["What happened"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Who fixes it"},"children":["Who fixes it"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Retry"},"children":["Retry"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["500"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYSTEM_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An unhandled fault inside the gateway"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Us"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["500"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INTEGRATION_CONFIG_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The merchant's stored integration record is wrong, such as a bad MID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Us, with the merchant's boarding data"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not until it is corrected"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["502"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DOWNSTREAM_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The gateway reached the processor and could not use the reply"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Us"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes, but reconcile first"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["503"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PROCESSOR_UNAVAILABLE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The processor is down or unreachable, and did not process the request"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The processor"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes, with backoff"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["502"]}," are not interchangeable."]}," ","A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}," means the processor was never reached, so no transaction exists."," ","A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["502"]}," means it was reached and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["may have seen the transaction"]},"."," ","A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["503"]}," means the processor did not process the request, so no transaction"," ","exists, and a retry after a backoff is safe."," ","There is no idempotency key, so retrying a payment after a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["502"]}," without"," ","reconciling first can charge twice. See"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/get-started/errors"},"children":["Errors and retries"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-the-openapi-description-declares","__idx":6},"children":["What the OpenAPI description declares"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The description declares ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["eight"]}," of these thirteen on its operations:"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_REQUEST_DATA"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NOT_AUTHENTICATED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UNAUTHORIZED_ACTION"]},","," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RESOURCE_NOT_FOUND"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DUPLICATE_ACTION"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYSTEM_ERROR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DOWNSTREAM_ERROR"]}," and"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PROCESSOR_UNAVAILABLE"]},". The last is named in the description of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["503"]}," ","response, which carries no example yet."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The other five — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_ACTION"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REQUIRED_DATA_MISSING"]},","," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AMOUNT_LIMIT_EXCEEDED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VELOCITY_LIMIT_EXCEEDED"]}," and"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INTEGRATION_CONFIG_ERROR"]}," — arrive from the processor-mapping layer and are not"," ","in the description yet."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["So ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["a generated SDK's error enum is not the whole list."]}," Handle an unrecognized"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_code"]}," by falling back on the HTTP status rather than throwing."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-invalid_action-conditions","__idx":7},"children":["Common ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_ACTION"]}," conditions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All of these return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_ACTION"]},". The code stays the same and the"," ","message narrows."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Capture"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Transaction already captured"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The transaction is not in an authorized state"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cannot capture a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SALE"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cannot capture an ACH transaction"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cannot capture a declined transaction"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Cancel"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Transaction already canceled"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cannot cancel a declined transaction"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cannot cancel a transaction that has already settled"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Refund"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cannot refund a transaction that has not settled"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Already refunded in full"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The amount exceeds the remaining refundable amount"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The amount exceeds the original transaction amount"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cannot refund a canceled transaction"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Batch close"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A batch close is already in progress"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["No open batch available to close"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payment method and transaction type"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Both card data and a payment token were sent"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Both ACH data and a payment token were sent"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTH"]}," is not supported for ACH"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYOUT"]}," is not supported for cards"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CAPTURE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCEL"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REFUND"]}," are not valid types for creating a transaction"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"declines-are-not-errors","__idx":8},"children":["Declines are not errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["A declined payment is a successful API call."]}," It returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," with a"," ","transaction whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]},". No ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_code"]}," is set, because nothing"," ","went wrong with the request."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"result\": \"DECLINED\",\n  \"response_code\": \"51\",\n  \"response_description\": \"Insufficient funds\",\n  \"batch_id\": null\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Three tests separate the two:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Did the processor make a decision?"]}," A decision, even a negative one, is a"," ","decline. A failure to reach a decision is an error."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Would resending the identical request help?"]}," If no, because the issuer"," ","refused, it is a decline."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Is there a field to fix or a setting to change?"]}," If yes, it is an error. If"," ","the request was valid and the money simply was not authorized, it is a"," ","decline."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Treating a decline as an error is the most expensive mistake on this page. A"," ","client written against a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4xx"]}," will retry it, alert on it, or show the cardholder"," ","a system fault — and none of those is right."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/payments/handle-declines"},"children":["Handle declines"]}," covers what to do with each"," ","outcome."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"reading-the-processors-own-code","__idx":9},"children":["Reading the processor's own code"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source.code"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source.message"]}," pass through unchanged, so you see exactly"," ","what TSYS or VeriCheck said."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Processor"},"children":["Processor"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code shape"},"children":["Code shape"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TSYS"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Two characters"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["13"]}," invalid amount, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["51"]}," insufficient funds"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["VeriCheck"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TN"]}," and three digits"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TN007"]}," routing number not provided"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These are for humans. Quote them in a support ticket alongside the"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-request-id"]}," header; do not branch on them, because the mapping between"," ","processor codes and our codes can change without our contract changing."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Never show a processor code or message to a cardholder."]}," \"Do not honor\" and"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["51"]}," mean nothing to them, and some imply things about their account that are not"," ","yours to relay."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":10},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/get-started/errors"},"children":["Errors and retries"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/payments/handle-declines"},"children":["Handle declines"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/reference/known-limitations"},"children":["Known limitations"]}]}]}]},"headings":[{"value":"API response codes","id":"api-response-codes","depth":1},{"value":"The error envelope","id":"the-error-envelope","depth":2},{"value":"The codes","id":"the-codes","depth":2},{"value":"Something is wrong with the request","id":"something-is-wrong-with-the-request","depth":3},{"value":"You are not allowed","id":"you-are-not-allowed","depth":3},{"value":"Something failed on our side or the processor's","id":"something-failed-on-our-side-or-the-processors","depth":3},{"value":"What the OpenAPI description declares","id":"what-the-openapi-description-declares","depth":2},{"value":"Common INVALID_ACTION conditions","id":"common-invalid_action-conditions","depth":2},{"value":"Declines are not errors","id":"declines-are-not-errors","depth":2},{"value":"Reading the processor's own code","id":"reading-the-processors-own-code","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"API response codes","shortTitle":"Response codes","intro":"Every error the API returns, what each one means, and whether retrying is safe. Also the difference between an error and a decline, which is the distinction that matters most.","type":"reference","seo":{"title":""}},"lastModified":"2026-10-22T03:04:53.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/reference/response-codes","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}