Error Codes & Troubleshooting

Handle uses standard HTTP status codes along with granular error codes in the response body to help you diagnose and handle issues.

Error Response Format

{
  "status": "error",
  "code": "NO_ACTIVE_MANDATE",
  "message": "The customer has no active bank mandate on Handle."
}

HTTP Status	Error Code	Description & Developer Action
`401 Unauthorized`	`UNAUTHORIZED`	Invalid, expired, or missing `sk_live_...` / `sk_test_...` key. Verify your Authorization header.
`404 Not Found`	`HANDLE_NOT_FOUND`	The `@handle` or phone number is not registered on Handle. Prompt user to check spelling or sign up.
`400 Bad Request`	`NO_ACTIVE_MANDATE`	Customer has no active bank account mandate. Prompt customer to activate their bank mandate in the Handle mobile app.
`409 Conflict`	`DUPLICATE_REFERENCE`	The `reference` has already been used. Generate a fresh unique reference for new charges.
`400 Bad Request`	`USER_DECLINED`	The customer explicitly tapped Decline on their in-app push notification prompt.
`402 Payment Required`	`INSUFFICIENT_FUNDS`	The customer’s bank rejected the debit due to insufficient balance.
`408 Request Timeout`	`AUTHORIZATION_TIMEOUT`	Customer did not approve the push prompt within the 3-minute window. Allow customer to retry.
`429 Too Many Requests`	`RATE_LIMITED`	Exceeded API rate limits. Implement exponential backoff and respect the `Retry-After` header.
`500 Server Error`	`INTERNAL_SERVER_ERROR`	An unexpected error occurred on Handle. Contact support if this persists.