{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Reefpay Docs","description":"Reefpay 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":"errors-and-retries","__idx":0},"children":["Errors and retries"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two different things can go wrong with a payment, and they look nothing alike."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The request failed."]}," The API returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4xx"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5xx"]}," with an error body."," ","Nothing was charged."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The payment was declined."]}," The API 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"]},". The request worked; the issuer said no."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This page is about the first. For the second, see"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/payments/handle-declines"},"children":["Handle declines"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-error-envelope","__idx":1},"children":["The error envelope"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every failure returns 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":"What it carries"},"children":["What it carries"]}]}]},{"$$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 to branch on. Always present"]}]},{"$$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":["That code in words, for a log"]}]},{"$$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 name to problem, when the failure was about specific fields. Otherwise 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 code and text, passed through unchanged. Null fields when the gateway failed before reaching a processor"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Branch on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_code"]},", never on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_message"]},"."]}," The message is prose and may"," ","be reworded. The code is part of the contract."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source"]}," is for your support and reconciliation, not for your control flow. It"," ","tells you what TSYS or VeriCheck said, in their vocabulary, so a support ticket"," ","can quote it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-codes","__idx":2},"children":["The codes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Seven, and that is the whole list."]},{"$$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":"Status"},"children":["Status"]},{"$$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":"Safe to retry"},"children":["Safe to retry"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_REQUEST_DATA"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The request is malformed or a field is invalid. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details"]}," names the fields"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No — fix the request"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","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 — check both headers"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","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 allowed to do this"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","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 transaction, client, or integration"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No — check the ID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DUPLICATE_ACTION"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The action conflicts with the resource's current state"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No — read the resource first"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYSTEM_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A fault inside the gateway"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes, with backoff"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","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 its reply"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes, but read the next section first"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," does not distinguish a missing header from a wrong key. If you get one,"," ","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 — a missing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Client-Id"]}," produces the same answer."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Not every operation can return every code. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}," is declared on 11 of the 19"," ","operations, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]}," on 7, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["502"]}," on only 4: creating, capturing, and canceling a"," ","transaction, and closing a batch."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"500-and-502-are-not-the-same","__idx":3},"children":["500 and 502 are not the same"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is the distinction that matters when money is involved."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}]}," is a fault inside the gateway. The processor was never reached, so"," ","no transaction exists."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["502"]}]}," means the gateway reached the processor and could not use what came"," ","back. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The processor may have seen the transaction."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both are safe to retry in the sense that the API will accept the request again."," ","Only one is safe to retry ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["blindly"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["After a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["502"]}," on a payment, reconcile before retrying."]}," Call"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/transactions"]}," filtered to the window in question and look for a"," ","transaction matching what you sent. The API has ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["no idempotency key"]},", so a"," ","retry that the first attempt already completed creates a second charge."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"retrying","__idx":4},"children":["Retrying"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["502"]},". Do not retry ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]}," — the"," ","request will fail the same way until you change it."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use exponential backoff with jitter: wait a short interval, double it each"," ","attempt, and add a small random offset so a fleet of clients does not retry in"," ","lockstep. Three or four attempts is usually enough; past that, the failure is not"," ","transient."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There is no rate limit response today. If you are sending enough traffic to worry"," ","about one, talk to your implementation contact rather than designing around a"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}," the API does not return."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"every-response-carries-a-request-id","__idx":5},"children":["Every response carries a request ID"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Successful or not, every response includes an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-request-id"]}," header holding a"," ","GUID."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"x-request-id: 73039bd9-c380-4186-bffe-259125144a56\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Log it with every request you send."]}," It is what lets support trace one specific"," ","call through the gateway. A support ticket without it usually turns into a"," ","request for it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-to-show-a-person","__idx":6},"children":["What to show a person"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not put ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_code"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_code"]},", or anything from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source"]}," in front of a"," ","cardholder. \"Do not honor\" and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["51"]}," mean nothing to them and sometimes imply"," ","something untrue about their account."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Map to a short, actionable sentence — \"That card was declined. Try another card\""," ","— and keep the codes in your logs, where they are useful."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":7},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$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/get-started/authentication"},"children":["Authentication"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/get-started/environments"},"children":["Environments and test data"]}]}]}]},"headings":[{"value":"Errors and retries","id":"errors-and-retries","depth":1},{"value":"The error envelope","id":"the-error-envelope","depth":2},{"value":"The codes","id":"the-codes","depth":2},{"value":"500 and 502 are not the same","id":"500-and-502-are-not-the-same","depth":2},{"value":"Retrying","id":"retrying","depth":2},{"value":"Every response carries a request ID","id":"every-response-carries-a-request-id","depth":2},{"value":"What to show a person","id":"what-to-show-a-person","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Errors and retries","shortTitle":"Errors and retries","intro":"One error envelope covers every failure, and one field tells you whether retrying is safe. This page covers both, and the difference between a declined payment and a failed request.","type":"reference","seo":{"title":""}},"lastModified":"2026-09-17T08:34:37.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/get-started/errors","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}