You're offline — reconnect to continue buying or checking your wallet.
Reference

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.

Error response
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Wallet balance is insufficient for this operation.",
    "details": { "...": "present on validation errors only" }
  }
}
VALIDATION_ERRORHTTP 422

The 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 404

The 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 409

A 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 409

This 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 403

The 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 403

This API client key has been revoked.

What to do: Provision a new key pair, this one will never work again.

AUTHENTICATION_ERRORHTTP 401

Incorrect 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 401

No bearer token was supplied.

What to do: Add an Authorization: Bearer <access_token> header, get one from POST /partner/auth/token first.

TOKEN_EXPIREDHTTP 401

The 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 401

The 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 401

The 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 400

X-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 429

This 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 429

Too 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 402

The 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 503

No 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 500

Something went wrong on TopupRelay's own side.

What to do: Not caused by your request. Retry once, and contact TopupRelay if it keeps happening.