Docs

Errors

Every failed API response is JSON with a code, a plain-language message and a request id. Show the message. Log the request id.

Shape

{
  "error": {
    "code": "invalid_credentials",
    "message": "Wrong email or password.",
    "request_id": "req_..."
  }
}

Common codes

code	Meaning
unauthorized	Missing or unknown API key or session.
invalid_request	Body failed validation. Read the message.
idempotency_key_required	Add Idempotency-Key on writes.
idempotency_key_reuse	That key was used with a different body.
live_not_available	Finish sandbox tests and wait for approval.
method_unavailable	That way of paying is down. Offer another method.
mwk_only	Currency must be MWK.
card_data_forbidden	Do not send card numbers, CVVs or PINs.
pooled_funds_forbidden	Settlement account already belongs to another merchant.
invalid_state	The payment cannot do that in its current status.

HTTP status

400 validation, 401 auth, 403 forbidden, 404 missing, 409 conflict or illegal state, 5xx we failed. Retry 5xx with the same Idempotency-Key. Do not retry 409 with a new body and the same key.