Skip to main content

Disbursement API Error Reference

This document outlines the possible error responses returned by our disbursement APIs. Each error is designed to indicate a specific failure condition, helping clients to debug issues effectively and take appropriate actions.

All errors will return a JSON object with the following structure:

{
  "gateway_status": "rejected",
  "message": "<description of the error>"
}

Error List and Explanations​

1. Please enter a valid 11 digit phone number Starting with '01'​

  • Cause: Invalid Bangladeshi phone number format. Applicable for BKASH_P2C and NAGAD_P2C.
  • Expected Format: An 11-digit number starting with 01 (e.g., 01XXXXXXXXX).
  • Action: Validate input phone number before sending the request.

2. Please enter a valid 11 digit phone number Starting with '03'​

  • Cause: Invalid Pakistani phone number format. Applicable for EASYPAISA_P2C and JAZZCASH_P2C.
  • Expected Format: An 11-digit number starting with 03 (e.g., 03XXXXXXXXX).
  • Action: Ensure proper formatting based on country-specific rules.

3. CVU Number and CUIT are required for Mercado Pago P2P.​

  • Cause: Required fields for Mercado Pago P2P transfer are missing.

  • Required Fields:

    • CVU: Unique Virtual Key.
    • CUIT: Tax Identification Number.

  • Action: Ensure both values are provided when initiating a Mercado Pago P2P payout.

4. Server Error!​

  • Cause: Unexpected failure in the upstream service or internal server.
  • Severity: Critical.
  • Action: If persistent, contact support.

5. Insufficient Balance.​

  • Cause: The sender’s wallet or funding source does not have enough balance.
  • Action: Check available balance before initiating payment.

6. Please choose another payment method for payout!​

  • Cause: The selected payout method is currently unavailable or restricted.

  • Possible Reasons:

    • PSP (payment service provider) is down.
    • Regulatory restrictions.

  • Action: Offer alternative payment options to the user.

7. Server Error, Please Try Again!​

  • Cause: General backend error—retryable.
  • Action: Advise retrying after a short delay. Log request payload for debugging if error persists.

8. Something went wrong​

  • Cause: A non-specific fallback error.
  • Action: Review request parameters. Check logs for any internal exception trace.

9. Unknown error occurred.​

  • Cause: An unhandled or uncategorized error state.
  • Severity: Medium to high.
  • Action: Log entire response. Report issue to the API team if reproducible.

10. Invalid type, <fieldName> (<expectedType>) <message>.​

  • Cause: One or more fields do not match expected data types.

  • Example:

    {
      "gateway_status": "rejected",
      "message": "Invalid type, amount (number) must be positive."
    }

  • Action: Review field type expectations as defined in the API schema. Validate input prior to API call.

11. Invalid Signature​

  • Cause: The request signature verification failed.
  • Action: Recalculate the signature as per documentation. Ensure correct encoding and key.

12. Unauthorized​

  • Cause: API request is not authenticated.
  • Action: Ensure your IP address is whitelisted.

🔁 Query Policy​

  • For server-related errors (e.g., Server Error!, Unknown error occurred.), clients may query the order status using Query by Merchant Disbursement ID.
  • For validation errors (e.g., invalid phone numbers, missing fields), do not retry. Fix the client request first.

📞 Need Help?​

If you're unable to resolve an error using this guide, please contact the Creedo Technical Team