Errors & Timeouts

Fat Zebra uses standard HTTP response codes to indicate success or failure of an API request. In general, codes in the 2XX range indicate success. Codes in the 4XX range indicate an error based on the information provided (e.g., a required parameter was omitted, a charge failed). Codes in the 5XX range indicate an error with Fat Zebra's systems.

Some 4XX errors can be handled programmatically (e.g., a card is declined) and include an error code that briefly explains the error reported.

HTTP status code summary

Status CodeSummary
200 - OKThe request was successfully completed.
201 - CreatedThe request was successful and a transaction was created.
400 - Bad RequestBad data was received.
401 - UnauthorisedYour API credentials were not valid.
403 - ForbiddenThe resource you were requesting is not available for your credentials. You will most commonly see this is you are attempting to fetch a payment or refund created by your live credentials with your test credentials.
404 - Not FoundThe requested object was not found.
422 - Unprocessable EntityThe data provided was unprocessable, however the syntax of the request was correct.
500, 502, 503, 504 - Server ErrorsSomething went wrong with Fat Zebra's systems or the underlying infrastructure.


When making requests to the Gateway it is important to understand transaction processing timeouts to ensure the best customer experience possible.

Fat Zebra sets a strict timeout of 45 seconds on transactions being processed against the card networks - this means that from the time a request arrives in Fat Zebra's systems, it is permitted to process for up to 45 seconds before the Gateway stops the transaction, and a timeout response sent back to the merchant systems. It is suggested that merchants allow up to 50 seconds for a transaction to complete before retrying.

When a transaction is timed out by the Gateway our systems will automatically issue a transaction reversal, to void any in-flight transactions in the event it may have been successfully processed.

If a merchant chooses to use a lower timeout when communicating with the Gateway it is important to ensure that a query and subsequent void is issued against the transaction reference, to avoid any orphaned transactions impacting card holders.