VTPE Product Information API Error Responses

Your Product Information API must return NOT_FOUND, ALREADY_PAID, and SERVICE_UNAVAILABLE errors to VTPE with the correct HTTP status and JSON format.

When VTPE calls your Product Information API (GET {API_URL}/{reference}), return the appropriate error code so VTPE can inform the customer about what went wrong. This page documents the three required error responses.

Error Response Format

All error responses from your Product Information API must use this JSON structure:

{
  "error": "CODE",
  "errorMessage": "Human-readable message"
}

The error field is the machine-readable code that VTPE uses to determine the error type. The errorMessage field is displayed to the customer.

Error Codes

NOT_FOUND (404)

Return this error when the requested reference does not exist in your system.

Property	Value
HTTP Status	404
Error Code	NOT_FOUND

{
  "error": "NOT_FOUND",
  "errorMessage": "Reference not found"
}

ALREADY_PAID (409)

Return this error when payment was already completed for this reference. This prevents the customer from paying twice for the same order.

Property	Value
HTTP Status	409
Error Code	ALREADY_PAID

{
  "error": "ALREADY_PAID",
  "errorMessage": "Payment already completed"
}

SERVICE_UNAVAILABLE (503)

Return this error when your service is temporarily unable to respond, for example during maintenance or an outage.

Property	Value
HTTP Status	503
Error Code	SERVICE_UNAVAILABLE

{
  "error": "SERVICE_UNAVAILABLE",
  "errorMessage": "Service temporarily unavailable"
}

VTPE uses the errorMessage value to inform the customer. Use clear, concise messages so the customer understands what went wrong.