Guides
A clear next step.
Use error codes, field-level validation and request history to understand and recover from failed requests.
A consistent error response
{
"message": "Request ID was already used for a different payment.",
"code": "idempotency_conflict",
"request_id": "support-request-uuid"
}Errors include message, code and a support request_id. Validation errors add errors, with messages grouped by field. Share the support ID with NuePay, not your secret.
Common error codes
| Code | Meaning / recovery |
|---|---|
invalid_credentials | Check the secret, environment and whether it was regenerated. |
validation_error | Correct fields in the errors object. |
invalid_amount | Use a valid positive amount within limits; payout principals must be whole UGX. |
idempotency_conflict | Retry the original payload or start a genuinely separate payment with a new UUID. |
conflicting_idempotency_keys | If both legacy and standard headers are supplied, their UUIDs must match. |
insufficient_funds | The wallet must cover the principal and fee. |
payout_setup_required | Complete verified bank payout setup before disbursing. |
access_denied | Check account eligibility, freezes and API access. |
provider_unavailable | Live processing is paused or unavailable. Read or retry existing accepted payments safely. |
test_key_required | Use a sandbox key for simulation. |
not_found | Check the reference, application and environment. |
rate_limit_exceeded | Wait before retrying; keep the same payment UUID. |
simulation_conflict | The test payment already has a different final outcome. |
internal_error | Check the existing transaction outcome and contact support with the request ID. |
Rate limits
Limits are 120 authenticated requests per key and environment per minute, 300 requests per IP per minute, and 20 failed authentications per IP per minute. HTTP 429 is a signal to back off.
Request history without secrets
API Keys includes 30 days of request history with application/environment filters. It records route templates, result codes, duration, support IDs and payment references. It excludes request bodies, headers, query strings, phone numbers, merchant references and secrets.