Error taxonomy: HTTP status is not the payment status

The single most common error in payment API design is confusing the HTTP status with the payment status. An HTTP status says what happened to the request: whether the bank received it, understood it, and accepted it for processing. The payment status says what happened to the payment: whether it was accepted, is being settled, has been credited to the beneficiary, or was rejected. For a business analyst, the requirement is to define this behaviour in the API specification, because the client builds against the specification and nothing else. These are different things, and they are always reported separately. A 202 Accepted response means the request was accepted for processing; it does not mean the payment settled or the beneficiary was credited. A client that treats 202 as settled will tell its customer the money has arrived when it has not. Source: ISO 20022 ExternalPaymentTransactionStatus1Code; API design guidance; bank API developer documentation. The HTTP status codes a payment API uses are a small set, and each has a precise meaning. 200 OK means the request succeeded and the response carries the result, used for retrieving a payment or a status. 201 Created means a new resource was created synchronously and its location is returned, used when a resource is created immediately. 202 Accepted means the request was accepted for processing and the outcome will arrive later, used for initiating a payment, requesting a cancellation, or submitting an enquiry. 400 Bad Request means the request is malformed: bad JSON, a wrong field type, or a missing mandatory field. 401 Unauthorized means the credentials are missing, expired or invalid. 403 Forbidden means the caller is authenticated but not allowed to do this. 404 Not Found means no resource with that identification exists. 409 Conflict means the request conflicts with the current state, such as cancelling a payment that has already settled, or reusing an idempotency key with a different body. 422 Unprocessable Content means the request is well formed but a business rule failed, such as an invalid creditor account with code AC01. 429 Too Many Requests means the client exceeded the rate limit. Every error response carries three things: the HTTP status, a business error code, and a human readable message. The business error code is a stable identifier the client can program against, such as INVALID_REQUEST, AC01, AMOUNT_LIMIT_EXCEEDED, or RATE_LIMITED. The human readable message explains the problem in plain language, such as the creditor account number is invalid. The API documentation must state this rule plainly, because a client that has to guess will guess wrong. The response may also carry a field path, pointing to the exact field that failed, and a link to the API documentation for that error. A client that receives a 422 with code AC01 and field creditorAccount knows exactly what to fix; a client that receives only a 400 with no code must guess. For a business analyst, the requirement is to define the error code for every failure the API can return, the HTTP status for each, and the message text, and to test each one with a real call. The payment status codes are the ISO 20022 set, and they must be used exactly as defined. ACTC means technical validation passed. ACCP means accepted for processing, an early acceptance. ACSP means accepted and settlement is in process, a later acceptance. ACSC means settlement is completed on the debtor account. ACCC means settlement is completed on the creditor account, and it is the only code that confirms the beneficiary was credited. RJCT means rejected, and it always carries a reason code such as AC01, AC04, AM04 or FF01. PDNG means pending. The words ACCEPTED and CANCELLED are not ISO 20022 status codes and must never be used as payment statuses in an API response. A client that sees ACCC can tell its customer the money has arrived; a client that sees ACSP can only say the payment is being processed. The status code is the single most important field in the API response, because the client builds its customer message from it. A business error code must be stable and documented. A client that programs against the code AC01 expects it to mean the same thing in every response, in every version of the API, and in every payment type. If the bank changes the meaning of AC01, or uses it for a different error in a different endpoint, the client's error handling breaks. The bank must therefore maintain a catalogue of error codes, with the meaning, the HTTP status, and the message for each, and must never reuse a code for a different error. The catalogue is part of the API specification, and a change to it is a breaking change that requires a new API version. For a business analyst, the requirement is to define the error catalogue, the code for each error, and the process for adding a new code. Validation errors deserve special care, because they are the most common errors a client will see. When a request fails validation, the response must identify every field that failed, not just the first one, so the client can fix all of them in one attempt rather than submitting the request repeatedly and discovering one error at a time. A test pack that does not cover this case will pass in the test environment and fail when a real client calls the API. Each failed field must carry its path, such as creditorAccount.iban, the reason it failed, such as invalid format, and the value that was supplied, so the client can see what it sent. A validation response that says only invalid request is a poor experience; a validation response that lists every failed field with its path and reason is a good one. Further reading: ISO 20022 ExternalPaymentTransactionStatus1Code; API design guidance; bank API developer documentation. Last reviewed 7 November 2026.