Errors

Kwugwo uses conventional HTTP status codes: 2xx means success, 4xx means the request can’t succeed as sent, and 5xx means something went wrong on our side or at the PSP.

Branch on the HTTP status first, then on code (business errors) or errors[].field (validation errors). Log message, but don’t match on its text.

Status codes

Status	Meaning
`200 OK`	Success. Creates also return `200`.
`400 Bad Request`	Malformed JSON, or an invalid value such as a bad pagination cursor.
`401 Unauthorized`	Missing, malformed or revoked secret key, or a key from the other environment.
`402 Payment Required`	Your Kwugwo subscription can’t cover this charge. Top up in the dashboard.
`404 Not Found`	The resource doesn’t exist on the workspace that owns this key.
`405 Not Allowed`	The request is valid, but not in the resource’s current state (e.g. cancelling a paid ugwo, refunding a failed charge).
`409 Conflict`	A duplicate (`ref` or email already used), or charging an ugwo that is already paid or cancelled.
`422 Unprocessable Entity`	One or more body fields or query parameters failed validation.
`500 Internal Server Error`	Something went wrong inside Kwugwo. See Retries.
`503 Service Unavailable`	Payment routing failed: no PSP on the checkout’s route could take this charge right now. Nothing was charged.

A declined payment or refund is not an HTTP error. It comes back as 200 with status: "failed" and an error object on the activity or refund.

Error bodies

Bodies are always JSON. Their shape depends on the kind of error:

Business errors (400, 402, 405, 409, 500, 503)
Not found (404)
Validation (422)
Authentication (401)

{
  "message": "nzube.ugwo.error.ref_already_exists",
  "code": "already_exists",
  "params": []
}

string

A stable, machine-readable class. See Error codes.

string

A specific message key (sometimes the PSP’s own text). Each endpoint’s Errors table lists the ones it returns.

array | object

Values for placeholders in message. Usually empty.

{
  "code": 404,
  "message": "nzube.ugwo.error.not_found"
}

{
  "type": "validation.error",
  "title": "An error occurred",
  "status": 422,
  "detail": "ugwo_activity \"act.VCvr.aaaaaaaaaaaaaaaaaaaaaaaa\" not found\nThis value should be 1 or more.",
  "message": "Validation failed",
  "errors": [
    { "field": "ugwo_activity", "message": "ugwo_activity \"act.VCvr.aaaaaaaaaaaaaaaaaaaaaaaa\" not found" },
    { "field": "amount", "message": "This value should be 1 or more." }
  ]
}

object[]

One entry per problem; a field can appear more than once. field is the parameter name as you sent it: a body field (amount, provider for a medium parameter, meta) or a query parameter (limit, filters[status]). message is a readable explanation.

string

All messages joined with newlines, handy for logs.

The same shape is used for invalid body fields and invalid query-string parameters (e.g. limit=500).

{
  "message": "Invalid token"
}

message is one of No token provided, Invalid token format, Invalid token type or Invalid token.

Error codes

`code`	HTTP	Meaning
`invalid_value` / `invalid_argument`	`400`	A parameter has an unusable value, e.g. `pagination.error.invalid_cursor`.
`no_subscription`	`402`	No subscription balance covers this charge.
`not_found`	`404`	The resource doesn’t exist.
`not_allowed`	`405`	Not possible in the current state. `message` says why.
`already_exists`	`409`	Duplicate `ref`/email, or the ugwo is already paid or cancelled.
`unknown_error`	`500`	Internal error at Kwugwo.
`payment_routing_error`	`503`	No PSP on the route could take the charge. `message` is the failure message set in your checkout’s routing rules, or `nzube.ugwo.error.routing_failed`.

Retries and idempotency

Kwugwo has no Idempotency-Key header. Use ref instead: it is unique per workspace on ugwos and refunds, so a retried create can never produce a duplicate.

Request	Safe to retry?
Any `GET`	Yes, on network errors and `5xx`. Back off exponentially.
`POST /v1/ugwo` with a `ref`	Yes. A `409 ref_already_exists` means the first attempt landed. Find it on the first page of List ugwos (newest first) by matching `ref`, or wait for its `ugwo.created` webhook.
`POST /v1/ugwo` without a `ref`	No. You may create a duplicate payment. Always send `ref`.
`POST /v1/ugwo/{uid}/activities`	With care. A retry creates a second open attempt, and if the customer completes both you get a double charge. After an ambiguous failure (timeout, `500`), list activities first and reuse an open one. A `503` is safe to retry: no activity was created.
`POST /v1/refunds` with a `ref`	Yes. `409` means it already exists. On a `500`, list refunds for the activity before retrying.
`PUT …/actions/{uid}`	Yes. Submitting to an action that is no longer `pending` returns it unchanged.

Common pitfalls

401 on every request, even with a valid key

The header must be exactly Authorization: Bearer sk.…. Check for a trailing newline from your secrets store, and that you’re using the sandbox key against sandbox-api.kwugwo.africa (or the live key against api.kwugwo.africa). Regenerating a key revokes the old one immediately.

422 provider should not be blank when charging

Medium parameters belong in data.medium_params, not directly in data. A provider placed at data.provider is ignored, so the request fails as if you sent none. See Charge an ugwo.

404 for an ugwo you just created

IDs are scoped to the workspace and environment of the key. A sandbox ID (ending in _t) is never found with a live key.

405 when creating an ugwo

amount_too_low / amount_too_high: amounts are in the smallest unit, so ₦5,000 is 500000. currency_not_allowed: none of your PSPs is set up for that currency.

405 checkout_not_found when charging

The ugwo has checkout: null. Pass a checkout on create, or set up routing rules in the dashboard so one is picked automatically.

503 payment_routing_error when charging

None of the PSPs on the checkout’s route could take the charge (for example, every PSP on the route rejected it or is unavailable). No activity is created, no webhooks are sent, and the ugwo stays requires_ugwo. Retry after a short wait or offer another medium, and check your PSP connections and routing rules in the dashboard. If you set a custom failure message in your routing rules, it’s returned as-is in message, so you can show it to the customer.For mediums that take a provider (ussd, pay_with_bank), a bank that no PSP on the checkout supports is rejected earlier, with a 422 on provider.

409 already_processed when charging

The ugwo is already paid (or refunded) or was cancelled. Fetch it to check status; there is nothing left to collect.

A refund came back 200 but nothing was refunded

Check status. A PSP declining a refund is a normal outcome: "status": "failed" with the reason in error. For bank-transfer and USSD payments, you may need to send a destination.

Get started

Plugins

Guides

Concepts

API basics

Payments (Ugwo)

Activities

Next actions

Refunds

Customers (Onye)

Checkouts

Status codes

Error bodies

Error codes

Retries and idempotency

Common pitfalls

​Status codes

​Error bodies

​Error codes

​Retries and idempotency

​Common pitfalls

Status codes

Error bodies

Error codes

Retries and idempotency

Common pitfalls