{"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.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"error-handling","__idx":0},"children":["Error handling"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"http-status-codes","__idx":1},"children":["HTTP status codes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every API response includes an HTTP status code that indicates the result of the request."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"success-codes","__idx":2},"children":["Success codes"]},{"$$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":{"align":"left","data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["OK"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Request succeeded. The response body contains the requested data."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Created"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["A new resource was created successfully."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"client-error-codes","__idx":3},"children":["Client error codes"]},{"$$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":{"align":"left","data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Retry?"},"children":["Retry?"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Bad request"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The request body is malformed or contains invalid data. Check field names, types, and required fields."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["No — fix the request"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Unauthorized"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Missing or invalid API key, or invalid credentials on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/auth/keys"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["No — check credentials"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Forbidden"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Valid API key but insufficient permissions for the requested resource or action."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["No — check account role"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Not found"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The requested resource does not exist. Verify the endpoint URL and resource ID."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["No — check resource ID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Conflict"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The request conflicts with the current resource state (for example, voiding an already-settled transaction)."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["No — check resource state"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Too many requests"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Rate limit exceeded. Wait and retry with exponential backoff."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Yes — back off and retry"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"server-error-codes","__idx":4},"children":["Server error codes"]},{"$$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":{"align":"left","data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Retry?"},"children":["Retry?"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Internal server error"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Unexpected server error."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Yes — retry with backoff"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["502"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Bad gateway"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Gateway received an invalid response from an upstream service."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Yes — retry with backoff"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["503"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Service unavailable"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The service is temporarily overloaded or under maintenance."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Yes — retry with backoff"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["504"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Gateway timeout"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The upstream service did not respond in time."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Yes — retry with backoff"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-response-format","__idx":5},"children":["Error response format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a request fails, the response body contains a structured JSON object with details about the error."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"error\": {\n    \"status\": 400,\n    \"message\": \"Invalid request body\",\n    \"details\": [\n      {\n        \"field\": \"amount\",\n        \"message\": \"Amount must be a positive integer\"\n      }\n    ]\n  },\n  \"correlation_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\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":{"align":"left","data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["HTTP status code (mirrors the response status)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Human-readable summary of the error"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.details"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Array of field-level errors (when applicable)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.details[].field"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The request field that caused the error"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.details[].message"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Description of the validation failure"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["correlation_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["UUID for tracing; include this when contacting support"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"transaction-response-codes","__idx":6},"children":["Transaction response codes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Transaction responses include processor-level codes in addition to HTTP status codes. A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]}," response does not necessarily mean the payment was approved — check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_status"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_code"]}," fields."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"TRANSACTION-01JMRSPCK7XVNP3KS8F2W4T6Y\",\n  \"transaction_state\": \"authorized\",\n  \"response_status\": \"Approved\",\n  \"response_code\": \"00\",\n  \"response_message\": \"The API request is approved.\",\n  \"correlation_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\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":{"align":"left","data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction_state"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Current state of the transaction (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authorized"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["declined"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Human-readable result: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Approved"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Declined"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Error"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Processor result code (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["00"]}," for approved)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_message"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Detailed explanation of the result"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-processor-error-codes","__idx":7},"children":["Common processor error codes"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"tsys-credit-card-processor","__idx":8},"children":["TSYS (credit card processor)"]},{"$$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":{"align":"left","data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["00"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Approved"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["01"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Refer to card issuer"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["02"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Refer to card issuer, special condition"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["05"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Do not honor"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["12"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Invalid transaction"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["14"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Invalid card number"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["51"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Insufficient funds"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["54"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Expired card"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"vericheck-ach-processor","__idx":9},"children":["Vericheck (ACH processor)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ACH transactions may also return ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ACH return codes"]}," after settlement, which indicate issues discovered during clearing (for example, insufficient funds, account closed). These returns can arrive up to 60 days after the original transaction."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handling-errors-in-your-application","__idx":10},"children":["Handling errors in your application"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"check-the-response-status-code-first","__idx":11},"children":["Check the response status code first"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"https://files.modern-mermaid.live/images/1776268354769-mermaid-diagram-1776268354466.png","alt":"image"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"best-practices","__idx":12},"children":["Best practices"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Always check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_status"]}]}," on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]}," transaction responses. A successful HTTP response does not guarantee payment approval."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Log the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["correlation_id"]}]}," from every response. Include it in support requests so the team can trace the request."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Map processor codes to person-friendly messages."]}," Do not display raw codes like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["05"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["51"]}," to persons. Instead, map them to clear messages like \"Your card was declined. Please try a different payment method.\""]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Implement retry logic"]}," for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5xx"]}," errors using exponential backoff with jitter. Always include an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]}," header on retries to prevent duplicate transactions."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Do not retry ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4xx"]}," errors"]}," (except ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]},"). These indicate a problem with the request that must be fixed before retrying."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For retry implementation details, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/get-started/integration-best-practices"},"children":["About best practices for integration"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"further-reading","__idx":13},"children":["Further reading"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/api-fundamentals/restful-design"},"children":["About RESTful design"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/api-fundamentals/request-response-structure"},"children":["Request and response structure"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/get-started/integration-best-practices"},"children":["About best practices for integration"]}]}]}]},"headings":[{"value":"Error handling","id":"error-handling","depth":1},{"value":"HTTP status codes","id":"http-status-codes","depth":2},{"value":"Success codes","id":"success-codes","depth":3},{"value":"Client error codes","id":"client-error-codes","depth":3},{"value":"Server error codes","id":"server-error-codes","depth":3},{"value":"Error response format","id":"error-response-format","depth":2},{"value":"Transaction response codes","id":"transaction-response-codes","depth":2},{"value":"Common processor error codes","id":"common-processor-error-codes","depth":2},{"value":"TSYS (credit card processor)","id":"tsys-credit-card-processor","depth":3},{"value":"Vericheck (ACH processor)","id":"vericheck-ach-processor","depth":3},{"value":"Handling errors in your application","id":"handling-errors-in-your-application","depth":2},{"value":"Check the response status code first","id":"check-the-response-status-code-first","depth":3},{"value":"Best practices","id":"best-practices","depth":3},{"value":"Further reading","id":"further-reading","depth":2}],"frontmatter":{"title":"Error handling","shortTitle":"Error handling","intro":"The {% $env.PUBLIC_BRAND_NAME %} API uses standard HTTP status codes and structured JSON error responses. Understanding these codes helps you build resilient integrations.","type":"reference","seo":{"title":""}},"lastModified":"2026-06-05T02:46:44.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/concepts/api-fundamentals/error-handling","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}