Error handling

Error response format

All API errors follow the same structure:

{
  "status": false,
  "message": "Bad Request",
  "data": null,
  "err_code": "INPUT_MALFORMED",
  "errors": {
    "field_name": ["Error message"]
  }
}

err_code: machine-readable code for programmatic handling
errors: field-level detail, present on validation errors
message: human-readable summary

HTTP status codes

Code	Meaning	Retryable
`400`	Validation error, missing field, business rule violation	No. Fix the request first
`401`	Invalid or missing API credentials	No. Check your API key and signature
`404`	Resource not found or endpoint doesn’t exist	No. Check the ID or URL
`429`	Rate limit exceeded	Yes. Back off and retry
`500`	Unexpected server error	Yes. Retry with exponential backoff

Retry strategy

For 429 and 5xx responses, retry with exponential backoff:

Wait 1s before the first retry
Double the wait on each subsequent attempt
Cap at 30s
Stop after 3 to 5 attempts and alert your team

For 4xx responses, retrying the same request will not help. Fix the request first.

What to show users vs what to log

Error type	Show to user	Log internally
Field validation (`400` with `errors`)	Yes, show the relevant field message	Yes
Business rule violation (`400`, no field errors)	Yes, generic “this action couldn’t be completed”	Yes, with full error body
Auth failure (`401`)	No, show “something went wrong”	Yes, check for key expiry or misconfiguration
Not found (`404`)	Only if the resource is user-facing	Yes
Rate limit (`429`)	No, retry silently	Yes
Server error (`500`)	Yes, “something went wrong, try again shortly”	Yes, alert your team

Never expose err_code or raw error bodies to end users.

Error categories

Malformed request

Invalid JSON, bad headers, or a signature that doesn’t verify.

{
  "status": false,
  "message": "Bad Request",
  "data": null,
  "err_code": "INPUT_MALFORMED",
  "errors": {
    "signature": ["Invalid Signature"]
  }
}

Object not found or access denied

The resource doesn’t exist or doesn’t belong to your organization.

{
  "status": false,
  "message": "Bad Request",
  "data": null,
  "err_code": "USR_UNVERIFIED",
  "errors": {
    "customer": ["Customer not found or access denied."]
  }
}

Missing required fields

A required field was omitted from the request body.

{
  "status": false,
  "message": "Bad Request",
  "data": null,
  "err_code": "REQ_FIELD_MISSING",
  "errors": {
    "customer_id": ["This field is required."],
    "tax_number": ["This field is required."]
  }
}

Blank field value

A field was included but left empty.

{
  "status": false,
  "message": "Bad Request",
  "data": null,
  "err_code": "INPUT_MALFORMED",
  "errors": {
    "customer_id": ["This field may not be blank."]
  }
}

Format or length violation

A field value doesn’t match the expected format or exceeds length limits.

{
  "status": false,
  "message": "Bad Request",
  "data": null,
  "err_code": "INPUT_MALFORMED",
  "errors": {
    "email": ["Enter a valid email address."],
    "name": ["Ensure this field has no more than 255 characters."]
  }
}

Business rule violation

The request is valid but conflicts with a business constraint.

{
  "status": false,
  "message": "Bad Request",
  "data": null,
  "err_code": "INPUT_MALFORMED",
  "errors": {
    "transaction": ["Transaction hash already linked to a payout"],
    "email": ["Email already in use."]
  }
}

Server error

{
  "success": false,
  "message": "Internal Server Error",
  "err_code": "SYS_INTERNAL_ERROR",
  "errors": "Unexpected error occurred. Please try again later.",
  "data": null
}

Retry with backoff. If it persists, contact support@dollarpe.xyz with the request ID and timestamp.

Getting Started

Integration guides

Country Specific Guides

Development & Testing

We Support

Error response format

HTTP status codes

Retry strategy

What to show users vs what to log

Error categories

Malformed request

Object not found or access denied

Missing required fields

Blank field value

Format or length violation

Business rule violation

Server error

​Error response format

​HTTP status codes

​Retry strategy

​What to show users vs what to log

​Error categories

​Malformed request

​Object not found or access denied

​Missing required fields

​Blank field value

​Format or length violation

​Business rule violation

​Server error

Error response format

HTTP status codes

Retry strategy

What to show users vs what to log

Error categories

Malformed request

Object not found or access denied

Missing required fields

Blank field value

Format or length violation

Business rule violation

Server error