Refund Errors

Error HandlingCopy URL

When processing refunds there are two types of errors that can occur:

1. Synchronous Errors that you get back as an http response to your requests
2. Asynchronous Errors that happens during asynchronous processing.

Synchronous ErrorsCopy URL

All API error responses follow a consistent format that includes details about what went wrong:

{
  "errors": [
    {
      "code": "invalid_request",
      "message": "doesn't match schema",
      "params": {
        "currency": {
          "reason": "value is not one of the allowed values [AUD]"
        },
        "remittance_information/unstructured": {
          "reason": "value must be a string"
        }
      }
    }
  ]
}

The errors array contains all the errors that occurred during the request. The code can be one of:

• invalid_request: The request is invalid as contains invalid parameters.
• not_found: You're trying to use a resource that doesn't exist or has been deleted (e.g. bank account, mandate, original_payin, etc.).
• idempotency_conflict: The idempotency key provided is not valid. This could mean that you try to reuse an idempotency key that was already used for a different request.
• internal_error: An internal error occurred while processing your request.
• method_not_allowed: The HTTP method used for the request is not allowed for the endpoint you're trying to access.
• forbidden: You do not have the necessary permissions to access the resource or perform the requested action.
• unauthorized: Authentication is required to access the resource. This means your oauth token is either missing or invalid. You need to provide valid oauth token in the request headers.
• rate_limit_exceeded: You have exceeded the allowed number of requests within a specific time period.
• service_unavailable: The service is temporarily unavailable. This usually indicates a problem on the server-side, and you should try again later.
• provider_error: The bank's system is temporarily down.

Asynchronous ErrorsCopy URL

Asynchronous errors are errors that happen during background processing of the refund. These errors can surface in two ways:

• on the latest_error field of the refund
• if the refund reaches the state failed, on the state_reason field of the refund.

Latest ErrorCopy URL

The latest_error field contains the latest error that occurred during the processing of the refund. This field is updated when a new error occurs. The latest_error field is only present if there was an error during processing.

Example latest_error object:

{
  "latest_error":{
    "code": "PAYEE_ACCOUNT_CLOSED",
    "message": "The payee account is closed",
    "network_error_code": "NPP_AC03"
  }
}

Example state_reason object:

{
  "status_details": {
    "reason": {
      "code": "MANDATE_INELIGIBLE_AMOUNT_EXCEEDED",
      "message": "Amount Requested Exceeds Mandate Limit"
    },
    "status": "FAILED"
  }
}