Error Handling

Guru Pay uses consistent and structured error responses to help you debug and recover from failed requests easily.

Error Response Format

All error responses follow the same JSON structure:

{
  "status": false,
  "status_code": 422,
  "message": "VALIDATION_ERROR",
  "errors": {
    "email": ["The email field is required."],
    "password": ["The password must be at least 8 characters."]
  }
}

Field	Type	Descriptio
status	boolean	Always false in case of an error.
status_code	integer	Standard HTTP status code
message	string	Machine-readable error type or message.
errors	array or object	Detailed error info (validation errors, system messages).

Common Error Types

HTTP Code	Message	Description
400	INTERNAL_SERVER_ERROR	Unexpected. server-side or integration error.
401	UNAUTHORIZED	Invalid or missing API token.
403	NO_PERMISSION	Authenticated but not authorized to access the resource.
404	NOT_FOUND	Resource or endpoint not found.
422	VALIDATION_ERROR	Request failed input validation.
429	Too Many Attempts.	Rate limit exceeded.
500	INTERNAL_SERVER_ERROR	Unhandled internal error.

Important: API responses reflect only the technical outcome of a request and do not represent the final business state of a payment. The authoritative and final payment status is delivered through the webhook event and should be treated as the source of truth.

More information about webhook events statuses can be found here: Transaction Event | Documentation