Documentation

Copy page

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

400 responses (validation failures, declines and other business errors) 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"
}

Field	Type	Description
statusCode	integer	HTTP status code
timestamp	string	ISO 8601 datetime of the error
path	string	The request path that caused the error
response.code	string or number	Application-level error code. Gateway codes are strings ("300"); service codes are numbers (900, 905). Compare it as a string
response.text	string	Human-readable error message
message	string	High-level error category

Other statuses

Authentication (401), permission (403), not-found (404), conflict (409) and login-limiter (429, 503) responses keep the same top-level fields but carry the reason in response.statusCode / response.message / response.error instead of code / text:

Code
{
  "statusCode": 401,
  "timestamp": "2025-03-03T15:04:05.000Z",
  "path": "/v1/public/transactions",
  "response": {
    "statusCode": 401,
    "message": "Unauthorized",
    "error": "Unauthorized"
  },
  "message": "Unauthorized"
}

Validation errors

Request validation failures (missing or malformed fields) use code 900 and carry the field errors as an array in response.message:

Code
{
  "statusCode": 400,
  "timestamp": "2025-03-03T15:04:05.000Z",
  "path": "/v1/public/customer",
  "response": {
    "code": 900,
    "message": [
      "firstName should not be empty",
      "email must be an email"
    ]
  },
  "message": "Http Exception"
}

---

HTTP status codes

Status	Meaning
200	Success
201	Resource created
400	Bad request — invalid input, validation failure, or declined transaction
401	Unauthorized — missing or invalid credentials
403	Forbidden — valid credentials but insufficient permissions
404	Not found — resource does not exist
409	Conflict — resource already exists or state conflict
429	Too many failed logins with these credentials — fix them and wait for Retry-After
503	A login with the same credentials is still in progress — retry shortly
902, 905, 906	Charge request errors — the application code is also used as the HTTP status
500	Internal server error — unexpected server-side failure

---

Application error codes

The response.code field pinpoints the specific failure reason. Gateway codes are returned as strings, service codes as numbers; always compare with String(code).

Gateway and processor codes (HTTP 400, string)

Code	response.text
"200"	Transaction was declined by processor
"201"	Do not honor
"202"	Insufficient funds
"203"	Over limit
"204"	Transaction not allowed
"220"	Incorrect payment information
"221"	No such card issuer
"222"	No card number on file with issuer
"223"	Expired card
"224"	Invalid expiration date
"225"	Invalid card security code
"226"	Invalid PIN
"240"	Call issuer for further information
"250" – "253"	Pick up card / lost / stolen / fraudulent card
"260" – "264"	Declined with further instructions (stop recurring, update cardholder data, retry in a few days)
"300"	Transaction was rejected by gateway
"400"	Transaction error returned by processor
"410", "411"	Invalid merchant configuration / merchant account inactive
"420", "421"	Communication error (gateway / issuer)
"430"	Duplicate transaction at processor
"440", "441"	Processor format error / invalid transaction information
"460", "461"	Processor feature not available / card brand not supported

Validation errors (HTTP 400, number)

Code	Description
900	Request validation failed — response.message lists the field errors
101	Field validation on routes with custom validators — the detail is in response.text

Charge request errors (HTTP status = code, number)

Code	Message
902	VaultId or PaymentToken is required
905	Card number is required. — card.number (masked) missing on a token charge
906	Customer with id ... not found — vault missing or owned by another merchant

Authentication errors

These use the response.statusCode / message / error shape described above, not code:

HTTP status	Meaning
401	Missing or invalid credentials / key hash
403	Valid credentials but insufficient permissions
429	Too many failed logins — see Retry-After and X-RateLimit-* headers
503	A login with the same credentials is still in progress

---

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();

  // Codes are strings for gateway errors and numbers for service errors: normalize first
  switch (String(error.response?.code)) {
    case "300":
      // Transaction rejected by gateway — ask customer to use a different card
      break;
    case "223":
      // Expired card
      break;
    case "905":
      // card.number missing on a token charge (HTTP status is also 905)
      break;
    case "900":
      // Request validation failed — error.response.message lists the fields
      break;
    default:
      // Unexpected error — log and alert
      console.error("API error:", error);
  }
}

---

Retrying requests

You may safely retry requests that fail with:

• 500 whose body has no response.code / statusCode: 400 — genuine server errors, with exponential backoff
• Network timeouts or connection errors

A 500 whose body carries code: 900 or statusCode: 400 is a validation or business error: fix the request instead of retrying.

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.