Error Codes

Learn about the different HTTP response codes we send for successful and failed API calls.

To provide you with the best experience, we aim to successfully process all API calls. However, financial transactions involve multiple systems and an API call can fail due to external factors in these systems. API calls can also fail due to other unforeseen circumstances such as human error while providing inputs, network errors, and intermittent connectivity.

We use standard HTTP response codes to indicate a successful or failed API call. All successful API calls return a 2XX response code. You can treat any non 2XX HTTP response as a failed call.

The table below lists the various HTTP response codes we return to indicate successful or failed API calls.

HTTP Response CodeDescriptionNext Step
2XXSuccessful API call.
4XXFailed API call.

There is an error in the information provided by you. For example:
  • Invalid authorization header.
  • Invalid path, body, or query parameters.
Check and correct the information passed in the API call.
5XXFailed API call.

This can either be because:
  • There was an error with our service provider's system.
  • There was an error with ZWITCH servers.
Try making the API call after some time.

Error Parameters

To make it easier for you to identify where the error occurred and how to rectify the error, we return an error message with all non 2XX HTTP response codes.

Shown below are sample error responses for different non 2XX HTTP response codes.

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid secret key."
  }
}
{
  "error": {
    "type": "invalid_method",
    "code": "resource_missing",
    "message": "API does not support this method.",
    "param": "null"
  }
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing_or_invalid",
    "message": "The type field must be one of vpa, account_number",
    "param": "type"
  }
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "duplicate_request",
    "message": "duplicate request"
  }
}
{
  "error": {
    "type": "internal_system_error",
    "message": "something went wrong",
    "trace_id": "bfa30905-e73b-8d86-f656-6c64ac308634"
  }
}
{
  "error": {
    "type": "service_provider_error",
    "code": "downstream_error",
    "message": "we are unavailable to process the request due to an error with our service provider. Please try again after some time"
  }
}

The below table gives a brief description of the different parameters in the error message sent with all non-2XX HTTP response codes.

ParameterTypeDescription
typestringType of the error. Possible values:
  • authentication_error: HTTP code 401.
  • invalid_method: HTTP code 405.
  • invalid_request_error: HTTP code 422.
  • internal_system_error: HTTP code 500.
codestringThe error short code. Possible values:
  • resource_missing: The resource you are trying to access does not exist in our database.
  • parameter_missing_or_invalid: This code is returned when:
    • The path parameter is missing.
    • The path parameter is invalid.
    • A mandatory body parameter is missing
    • A body parameter passed is invalid.
  • parameter_unknown: An unexpected parameter was sent in the request body.
  • duplicate_request : Returned when we receive the same request again in quick succession.
messagestringError description. This parameter tells you why the error occurred.

For example, The name_of_account_holder field is required.
paramstringThe parameter where the error occurred.

For example, name_of_account_holder.
trace_idstring500 Error Only

This is a unique identifier for the API call in our database.

Share this value with our Integrations Team if you face any issues with our APIs. This helps us identify the API call, debug the call, and provide you with a resolution.

Note: This value is also present in all our responses headers as x-zwitch-trace-id.