Errors

The API uses conventional HTTP status codes. 2xx means success, 4xx means the request was rejected, and 5xx means something went wrong on our side.

Error shape

All error responses are JSON. Errors raised at the edge (rate limits, unknown routes, gateway failures) carry error and request_id:

{
  "error": "amount must be > 0",
  "request_id": "6f3c7d1e-9a2b-4c8f-b5e0-2b1a7e9d0c33"
}

Errors raised by the payment layer are terser and may add machine-readable fields instead of request_id — for example an invalid key returns { "error": "Invalid API key" } and a failed wallet lookup returns { "error": "account_not_found", "code": "account_not_found", "reason": "…" }. The x-request-id response header is always present on every response, error or not — read it from the headers rather than the body.

Status codes

• 200 OK — request succeeded (queried resource, resolved failure).
• 201 Created — a new resource was created (approved charge or checkout session).
• 202 Accepted — request accepted but still pending (e.g. momo prompt awaiting customer).
• 400 Bad Request — invalid parameters (amount, network, phone).
• 401 Unauthorized — missing, revoked, expired, or invalid API key.
• 403 Forbidden — key lacks permission (e.g. live key on unapproved business, read key attempting a charge).
• 403 Forbidden — domain_blocked: live requests from a site we have blocked after review. See Identify your app.
• 404 Not Found — route does not exist or resource is not yours.
• 409 Conflict — Idempotency-Key was reused with a different body, or a matching request is still in flight.
• 429 Too Many Requests — rate limit exceeded, retry after the Retry-After header.
• 501 Not Implemented — provider_unsupported: the payout endpoints are retired; payouts run from the dashboard.
• 502 Bad Gateway — the upstream payment provider rejected or could not process the request. The transaction is recorded as failed with the provider's reason.
• 5xx — retry idempotent requests with exponential backoff and the same Idempotency-Key.

The upstream provider's code field (e.g. "01" for a declined MoMo charge) is separate from the HTTP status — see Provider codes.

Attribution warnings

Successful responses may include a x-wr-attribution-warning header when your request did not declare HTTP-Referer and X-Webrabbitmedia-Title. It is a warning, not an error — the request still processed — but add the headers so your integration stays reviewable. See Identify your app.

Handling errors in code

A call made with an invalid key returns 401. Always branch on the HTTP status first and log x-request-id from the response headers.

curl -i https://api.webrabbitmedia.com/v1/me \
  -H "Authorization: Bearer wr_test_not_a_real_key"

# HTTP/2 401
# x-request-id: 6f3c7d1e-9a2b-4c8f-b5e0-2b1a7e9d0c33
#
# {"error":"Invalid API key"}