Overview

Exceptions occur when an API operation fails to process a request payload. In such scenarios, error codes and its corresponding HTTP status codes help troubleshoot the possible failure reason. For example, in a scenario where a user provides invalid inputs such as card number, CVV or expiry date.

The sample error response given below shows the HTTP response body structure that is returned in case of errors:

HTTP Response Body:
{
  "errorCode": "ER007",
  "errorType": "INVALID_ARGUMENT_ERROR",
  "errorMessage": "Invalid argument error occurred. Check additionalInfo for more details.",
  "traceId": "adb0213f-63aa-48f4-9dda-d033fa1c6641",
  "additionalInfo": {
    "amount": "may not be null",
    "requestId": "may not be null"
  }
}
HTTP Status Code: 400


  • The corresponding HTTP status codes are mapped as 4xx or 5xx based on the 'Error Type'.

  • traceId is a unique identifier of the error being reported. It needs to be shared with Zeta while referring to any error response where support is needed.

Default Error Codes

To support better error handling, we iteratively improve and add more error codes to this list. Please expect to receive new unseen error codes in API responses. In such cases, we recommend you to revisit this section and add handling for new codes as well.


The following table lists the possible error codes and its descriptions that are generated by the payment API services:

Error Type

Error Code

Error Description

HTTP Status Code

INTERNAL_SERVER_ERROR

ER000

Unexpected server error occurred.

500

INVALID_ARGUMENT_ERROR

ER007

Invalid argument error occurred. Check additionalInfo for more details.

400

INVALID_TRANSITION

ER008

Transition not supported from current state.

422

TRANSACTION_NOT_FOUND

ER010

Transaction not found.

404

TRANSACTION_ALREADY_PRESENT

ER011

Transaction with given requestId already present

400

MISSING_REQUEST_PARAMETER

ER012

Missing request parameter

400

PRECONDITION_MISMATCH

ER013

IllegalStateException

400

INVALID_SOURCE

ER014

Invalid source id given

400

SAVE_FOR_FUTURE_DISABLED

ER015

SaveForFuture is not enabled for this source

401

INVALID_MERCHANT_INFO

ER016

Given merchant info is invalid

400

INVALID_API_KEY

ER017

Given API Key is not valid

400

MISSING_API_KEY_HEADER

ER019

apiKey header is missing

400

REFUND_AMOUNT_MISMATCH

ER021

Transaction amount and refund request amount should be same

400

REQUEST_TIMED_OUT

ER022

Request timed out.

408

CONCURRENT_UPDATE_ATTMEPTED

ER023

Transaction already modified by another request

422

INVALID_MERCHANT

ER024

Unauthorized pull request made for merchant

401

UNVERIFIED_SOURCE

ER025

Source not verified

400

UNAUTHORIZED_SOURCE_ACCESS

ER026

Unauthorized access to the source requested, user consent needed

401

SOURCE_NOT_FOUND

ER027

Source not found

404

BALANCE_RETRIEVAL_FAILED

ER028

Unable to retrieve balance for the source

500

AMOUNT_MISMATCH

ER033

Requested amount is different from amount mentioned in token

400

TRANSACTION_ALREADY_REFUNDED

ER041

Transaction already refunded

400

INVALID_REFUND_AMOUNT

ER042

Requested amount cannot be refunded for the transaction

400

UNAUTHORIZED_API_ACCESS

ER044

Unauthorized access to API

405

INVALID_PHONE_NUMBER

ER047

No user found for this phone number

403