Error Handling

The Strictly API uses standard HTTP status codes and a consistent JSON error body to communicate problems. Always check the status code first, then inspect the response object for the specific application-level error code.

Error response shape

All error responses follow this structure:

Code
{
  "statusCode": 400,
  "timestamp": "2022-04-11T22:54:13.822Z",
  "path": "/v1/public/payment/charge",
  "response": {
    "code": "300",
    "text": "Transaction was rejected by gateway."
  },
  "message": "Http Exception"
}

HTTP status codes

Application error codes

The response.code field contains a numeric string that pinpoints the specific failure reason.

Payment errors

Validation errors

Authentication errors

Handling errors in code

JavaScript — check status and code
const response = await fetch(
  "https://api.paywithzero.net/v1/public/payment/charge",
  { method: "POST", headers, body }
);

if (!response.ok) {
  const error = await response.json();

  switch (error.response?.code) {
    case "300":
      // Transaction declined — ask customer to use a different card
      break;
    case "302":
      // Card expired
      break;
    default:
      // Unexpected error — log and alert
      console.error("API error:", error);
  }
}

Python — handle error codes
response = requests.post(url, headers=headers, json=body)

if not response.ok:
    error = response.json()
    code = error.get("response", {}).get("code")

    if code == "300":
        # Declined — prompt user to retry with a different card
        pass
    elif code == "302":
        # Card expired
        pass
    else:
        raise Exception(f"API error {code}: {error}")

Retrying requests

:::warning Do not retry declined transactions automatically

A 400 with a payment error code (e.g. 300 — declined) indicates a definitive gateway response. Retrying the same request will not succeed and may trigger fraud detection.

:::

You may safely retry requests that fail with:

• 500 — server errors, with exponential backoff
• Network timeouts or connection errors

Always use idempotency when retrying write operations: store the transaction ID on your first successful attempt and check for it before retrying to avoid duplicate charges.