Errors

Errors Handling

The PayPaga API uses conventional HTTP response codes to indicate the success or failure of an API request.

Some 4xx errors that could be handled programmatically (e.g., Request validation failed) include additional information such as an error code to enable more nuanced error handling..

HTTP Status	Description
200	Request processed normally.
400	Problem consuming the request due to not adhering to the API specification.
401	Authorization required due to invalid, expired or missing authorization token.
402	Request processing failure.
403	The authorization token does not have permissions to perform the request.
404	The requested resource does not exist.
500 502 503 504	Server could not process the request due to an unexpected condition. We work hard to make them as rare as possible.

Error Response Format

All error responses follow this structure:

"error": {
  {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": {} // Optional additional context
  }
}

Error codes are uppercase strings with underscores, designed to be machine-readable for programmatic error handling, for example: VALIDATION_ERROR, UNAUTHORIZED, INTERNAL_ERROR.

Common Error Codes

HTTP status	Error code	Description	Additional details
400	BAD_REQUEST	Failed to parse the request body	Returned when the request body is malformed or cannot be parsed as valid JSON. Applicable to POST and PUT endpoints.
400	VALIDATION_ERROR	Request validation failed	Returned when validation of the request body or query parameters fails. The response may include details about which fields failed validation and why.
401	UNAUTHORIZED	Missing or invalid authorization token	Returned when the authorization token is missing, invalid, or expired.
403	FORBIDDEN	You do not have permission to access this resource	Returned when the authorization token does not have the necessary permissions to perform the requested operation.
404	NOT_FOUND	Requested resource not found	Returned when the requested resource does not exist.
409	MERCHANT_REFERENCE_ALREADY_EXISTS	Merchant transaction reference already exists	Returned when a transaction with the same merchant reference already exists.
500	INTERNAL_ERROR	Unexpected server error	Returned when an unexpected error occurs on the server.

Particular list of possible errors can be found in the documentation of each endpoint.

Errors Handling#

Error Response Format#

Common Error Codes#

Errors Handling

Error Response Format

Common Error Codes