Error codes
Every error, anywhere in the API, takes the same shape, the code field is what your own code should check, never the human-readable message, which can change wording over time.
{
"success": false,
"error": {
"code": "INSUFFICIENT_BALANCE",
"message": "Wallet balance is insufficient for this operation.",
"details": { "...": "present on validation errors only" }
}
}VALIDATION_ERRORHTTP 422The request body failed validation.
What to do: Check error.details.errors for exactly which field, and compare your request body against the example on that endpoint's doc page.
NOT_FOUNDHTTP 404The resource doesn't exist, or doesn't belong to you.
What to do: Double-check the id or reference in the URL. A test-key request can never see a live-key resource, or the other way round.
CONFLICTHTTP 409A general conflict, e.g. EMAIL_TAKEN.
What to do: The specific sub-code in error.code explains what's conflicting, usually something already exists.
DUPLICATE_REFERENCEHTTP 409This wallet operation has already been applied.
What to do: Safe to treat as a success, not a real failure, you (or a retry) already sent this exact operation once.
FORBIDDENHTTP 403The account or client exists but is suspended or revoked.
What to do: Contact TopupRelay, this isn't something you can fix by changing your request.
CLIENT_REVOKEDHTTP 403This API client key has been revoked.
What to do: Provision a new key pair, this one will never work again.
AUTHENTICATION_ERRORHTTP 401Incorrect email or password.
What to do: This is for the consumer login endpoint, not the partner API, double-check you're calling the right one.
TOKEN_MISSINGHTTP 401No bearer token was supplied.
What to do: Add an Authorization: Bearer <access_token> header, get one from POST /partner/auth/token first.
TOKEN_EXPIREDHTTP 401The access token has expired.
What to do: Access tokens last 60 minutes. Call POST /partner/auth/token/refresh with your refresh_token to get a new one.
TOKEN_INVALIDHTTP 401The token is malformed, revoked, or doesn't match the signing client.
What to do: Get a fresh token from POST /partner/auth/token, don't reuse or hand-edit an old one.
SIGNATURE_INVALIDHTTP 401The HMAC signature doesn't match, or a required header is missing.
What to do: The single most common error. Check: is api_secret exactly right (no extra space)? Does the signed path include /api/v1? Is the method upper-case (POST, not post)? See Authentication for the exact recipe, or use the no-code Postman setup to skip this entirely.
TIMESTAMP_EXPIREDHTTP 400X-Timestamp is missing or outside the ±5 minute window.
What to do: Your computer's clock is probably wrong, check the date/time settings. A cached/reused timestamp from an earlier request also triggers this, generate a fresh one every call.
REPLAY_DETECTEDHTTP 429This exact signed request has already been processed.
What to do: You sent the identical method, path, body, and timestamp twice. Generate a brand-new timestamp (and therefore signature) for every request, never cache one.
RATE_LIMIT_EXCEEDEDHTTP 429Too many requests in a short time.
What to do: Wait the number of seconds in the Retry-After response header, then try again. See Rate limits.
INSUFFICIENT_BALANCEHTTP 402The wallet can't cover this debit.
What to do: Nothing was charged. Fund the wallet (see Wallet & funding) and retry the same purchase.
PROVIDER_UNAVAILABLEHTTP 503No VTU provider or payment gateway could serve the request right now.
What to do: Not something caused by your request, wait a moment and retry. If this persists, contact TopupRelay.
INTERNAL_ERRORHTTP 500Something went wrong on TopupRelay's own side.
What to do: Not caused by your request. Retry once, and contact TopupRelay if it keeps happening.