Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.dubupay.com/llms.txt

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

When a request cannot be completed, the Dubu Pay API always returns a structured JSON body alongside an appropriate HTTP status code. This consistent format means you can write a single error-handling function in your integration and handle every failure case in the same way.

​
Error response format

Every error response follows this envelope: 
{
  "success": false,
  "message": "Human-readable description of the error",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email address"
    }
  ]
}
​
success
boolean
Always false for error responses.
​
message
string
A short, human-readable summary of what went wrong. Safe to display to end users for most error types.
​
errors
array
Present on validation errors (HTTP 400). Each element describes one invalid field.

​
HTTP status codes

StatusMeaningWhen you’ll see it
400 Bad RequestValidation errorOne or more request fields failed schema validation. Check the errors array for field-level details.
401 UnauthorizedAuthentication failureNo credentials were provided, the access token has expired, or the credentials are invalid.
403 ForbiddenAuthorization failureYou are authenticated but do not have permission for the requested action (e.g. your IP is not whitelisted).
404 Not FoundResource missingThe requested resource does not exist or has been deleted.
409 ConflictDuplicate resourceYou attempted to create a resource that already exists — most commonly registering with an email that is already in use.
422 Unprocessable EntityBusiness logic errorThe request was well-formed but could not be completed due to a business rule (e.g. trying to verify an email that is already verified).
429 Too Many RequestsRate limit exceededYou have sent too many requests in a short period. Wait for the number of seconds in the Retry-After response header before retrying.
500 Internal Server ErrorServer errorSomething unexpected went wrong on our side. If this persists, contact support.

​
Error codes

The message field on each error response often corresponds to a machine-readable error code. Use these to branch your error-handling logic:
CodeStatusDescriptionResolution
EMAIL_IN_USE409The email address is already registered.Use a different email or direct the user to log in.
INVALID_CREDENTIALS401Email/password combination is incorrect.Check credentials and try again. Do not expose which field is wrong to end users.
UNAUTHORIZED401Request is missing a valid authentication token or API key.Include Authorization: Bearer <token> or X-Api-Key: <key>.
INVALID_REFRESH_TOKEN401The refresh token is missing, malformed, or expired.Send the user back through the login flow to obtain a new token pair.
TOKEN_REVOKED401The refresh token was already used or revoked (e.g. after logout or password change).Re-authenticate.
IP_WHITELIST_REQUIRED403Your merchant account requires an IP whitelist but none is configured.Add at least one IP address to your whitelist in the dashboard.
IP_NOT_WHITELISTED403The requesting IP address is not in your merchant’s whitelist.Add the IP to your whitelist or make the request from a whitelisted address.
NOT_FOUND404The requested record does not exist.Verify the ID or identifier you used.
ALREADY_VERIFIED422The email address has already been verified.No action needed — proceed to login.
INVALID_OTP400The one-time code is incorrect or has expired.Request a new OTP using POST /auth/resend-otp or POST /auth/forgot-password.
WRONG_PASSWORD400The current_password supplied to the change-password endpoint is incorrect.Provide the correct current password.

​
Validation errors in detail

When you send a request body that fails schema validation, you receive HTTP 400 with an errors array containing one entry per invalid field: 
{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email address"
    },
    {
      "field": "password",
      "message": "Password must be at least 8 characters"
    }
  ]
}
Iterate over errors to show inline field-level feedback to your users.

​
Handling rate limits

Auth endpoints use a stricter rate limit than the general 100 requests/minute cap. When you receive a 429 response:
  1. Read the Retry-After header to find out how long to wait.
  2. Pause all requests to that endpoint for at least that many seconds.
  3. Implement exponential back-off in automated systems to avoid hitting the limit repeatedly.
Do not retry immediately after a 429 — further rapid requests will reset the window.