Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kwugwo.africa/llms.txt

Use this file to discover all available pages before exploring further.

The API uses standard HTTP status codes. The response body for an error is JSON and follows Symfony’s RFC 7807 Problem Details shape with one or two extensions for validation failures.

​
Status codes

CodeUsed when
200 OKThe request succeeded. Most successful writes also return 200.
400 Bad RequestThe body could not be parsed or a non-validation error occurred.
401 UnauthorizedMissing, malformed, or revoked secret key.
403 ForbiddenThe key is valid but the action is not permitted.
404 Not FoundThe resource does not exist on this workspace.
409 ConflictThe resource already exists or is in a state that blocks this action.
422 Unprocessable EntityOne or more fields failed validation.
500 Internal Server ErrorSomething broke on our side — safe to retry idempotent requests.

​
Error body

{
  "type": "https://tools.ietf.org/html/rfc2616#section-10",
  "title": "An error occurred",
  "status": 404,
  "detail": "ugwo.error.not_found"
}
The detail field is a translation key on most errors. The dashboard maps these to human strings; when integrating server-to-server, treat the status code as the source of truth and use detail for logging.

​
Validation errors

When a request fails validation, the response is 422 with a violations array describing each offending field: 
{
  "type": "https://symfony.com/errors/validation",
  "title": "Validation Failed",
  "status": 422,
  "detail": "amount: The amount must be an integer.",
  "violations": [
    {
      "propertyPath": "amount",
      "title": "The amount must be an integer.",
      "code": "ba785a8c-82cb-4283-967c-3cf342181b40"
    }
  ]
}
propertyPath matches the request-body field name.

​
Common pitfalls

Make sure the header is Authorization: Bearer <key>. A trailing newline, a sk_ prefix missing, or whitespace will all reject. Also: did you regenerate the key in the dashboard recently?
Ugwo IDs are scoped to the workspace that owns the key. If you created the ugwo with a test key, you cannot fetch it with a live key.
currency must be one of the supported ISO-4217 codes (e.g. NGN, GHS, KES). The full list lives on the Kwugwo Currency enum.
Allowed values are bank_transfer, mobile_money, and ussd. The medium must also be enabled for the currency on the workspace’s PSPs or checkout — a typo here will surface as a routing failure on the activity, not on ugwo creation.

​
Retries

The API does not yet support idempotency keys, so retry only on network errors or 5xx responses, and only for GET / state-checking calls. For POST calls that create an ugwo or activity, treat any ambiguous failure as “needs operator review” rather than auto-retrying — you may otherwise charge a customer twice.