Errors and recovery

Most API errors contain:

{
  "error": {
    "code": "COLLECTIONS_PAUSED",
    "message": "COLLECTIONS_PAUSED",
    "next_action": "correct_request_or_check_status"
  }
}

Validation failures return HTTP 422 with message and field-level errors.

HTTP status	Meaning and next step
401	Check the application token
403	Check the application's permissions
404	Check the ID or reference and its owning application
409	Inspect the existing payment or refund; the request conflicts with its recorded state
422	Correct the rejected fields or amount
429	Wait for the duration in Retry-After
503	Collections are paused or provider configuration is incomplete

Lost response

Read the payment using its original reference. Keep the original idempotency key for any recovery request. A connection error does not establish whether EcoCash accepted the payment.

Refund needs review

Check the customer's credited amount, reservation and provider receipt in the payment detail. A pending return keeps funds reserved until a verified result is available.