Error Handling and Reliability

This guide covers error handling patterns, HTTP status codes, retry strategies, and reliability best practices that apply across all mCards APIs.

HTTP Status Codes

Success Codes

Code	Meaning	When Returned
`200 OK`	Request succeeded	GET, PUT, PATCH requests
`201 Created`	Resource created	POST requests that create a new resource
`204 No Content`	Request succeeded, no body	DELETE requests

Client Error Codes

Code	Meaning	Action
`400 Bad Request`	Malformed request or invalid parameters	Fix the request body or parameters and retry
`401 Unauthorized`	Invalid or missing authentication	Verify your API key, secret, and HMAC signature
`403 Forbidden`	Valid credentials but insufficient permissions	Check your partner role assignments
`404 Not Found`	Resource does not exist or is not in your scope	Verify the resource UUID and your data scope
`422 Unprocessable Entity`	Request is well-formed but semantically invalid	Review the error details for validation failures
`429 Too Many Requests`	Rate limit exceeded	Back off and retry after the indicated period

Server Error Codes

Code	Meaning	Action
`500 Internal Server Error`	Unexpected server failure	Retry with exponential backoff
`502 Bad Gateway`	Upstream service unavailable	Retry with exponential backoff
`503 Service Unavailable`	Server temporarily overloaded	Retry with exponential backoff
`504 Gateway Timeout`	Request timed out	Retry with exponential backoff

Error Response Format

Error responses include a JSON body with details about what went wrong:

{
  "errors": [
    {
      "detail": "Description of the error",
      "source": {
        "pointer": "/data/attributes/field_name"
      }
    }
  ]
}

Use the detail field for debugging and the source pointer (when present) to identify which field caused the error.

Retry Strategy

When to Retry

Scenario	Retry?	Strategy
`5xx` server errors	Yes	Exponential backoff with jitter
`429` rate limit	Yes	Wait for the indicated retry period
`408` request timeout	Yes	Retry immediately, then backoff
`4xx` client errors (except 429)	No	Fix the request before retrying
Network timeout / connection refused	Yes	Exponential backoff with jitter

Exponential Backoff

For retryable errors, use exponential backoff with jitter:

wait_time = min(base_delay * 2^attempt + random_jitter, max_delay)

Recommended values:

Base delay: 1 second
Max delay: 60 seconds
Max retries: 5 attempts
Jitter: Random value between 0 and 1 second

Example (Python)

import time
import random

def retry_with_backoff(request_func, max_retries=5):
    for attempt in range(max_retries):
        response = request_func()
        if response.status_code < 500 and response.status_code != 429 and response.status_code != 408:
            return response

        wait = min(1 * (2 ** attempt) + random.uniform(0, 1), 60)
        time.sleep(wait)

    raise Exception("Max retries exceeded")

Timeouts

API Request Timeouts

Set appropriate timeouts for API calls:

Timeout Type	Recommended Value
Connection timeout	10 seconds
Read timeout	30 seconds

Webhook Response Timeouts

For partners responding to payment authorization webhooks (payment.* events):

mCards expects a response within a defined timeout window
The cardholder is waiting at the point of sale — respond as quickly as possible
If your service cannot respond in time, the DPE moves to the next payment account in rank order

Idempotency

Design your integration to handle duplicate requests gracefully:

Webhook handlers — The same event may be delivered more than once. Use the event payload to deduplicate (e.g., by transaction ID or event ID)
API writes — If a request times out and you are unsure whether it succeeded, it is safe to retry POST requests that create resources — duplicate creation attempts will return an appropriate error rather than creating duplicates

Best Practices

Log request and response details — Include the HTTP status code, response body, and request ID for debugging
Monitor error rates — Track 4xx and 5xx rates to detect integration issues early
Handle partial failures — When processing batches, handle individual item failures without aborting the entire batch
Use circuit breakers — If errors persist, temporarily stop sending requests to avoid cascading failures
Test in sandbox — Validate error handling in the sandbox environment before going to production

Related Guides

API Authentication and Credentials — Common authentication errors and troubleshooting
Webhooks API Concepts — Webhook delivery and retry behavior
Getting Started — Platform overview and quick start