Error Code Reference¶

This section documents all error codes returned by the PayAlo Merchant Gateway V2 API. Each error response includes a type URL that links to the corresponding error code page.

All V2 errors follow the RFC 7807 Problem Details format with content type application/problem+json:

{
  "type": "https://docs.payalo.com/errors/{specific-or-generic-code}",
  "title": "Short error category",
  "status": 400,
  "detail": "Human-readable explanation of this specific occurrence.",
  "errorCode": "{generic-code}"
}

How to read these errors¶

The two code-bearing fields play different roles:

errorCode — the generic category (validation_failed, bad_request, unauthorized, not_found, business_logic_error, internal_server_error). Use this for top-level branching; it never varies within a category.
type — a URL whose final path segment is the specific code that triggered the error (e.g. config_unsupported_currency, merchant_disabled, merchant_transactionid_duplicate). Use this when you need to react to a specific business or configuration rule.

For most validation errors (missing field, bad format, unsupported currency, disabled merchant), errorCode is "validation_failed" and the specific reason lives only in type and detail. For 422 business-logic errors with a dedicated code (e.g. duplicate merchant reference), errorCode and the final segment of type are the same value.

// Example: unsupported currency
{
  "type": "https://docs.payalo.com/errors/config_unsupported_currency",
  "title": "Validation failed",
  "status": 400,
  "detail": "Currency is not supported.",
  "errorCode": "validation_failed"
}

Synchronous API Error Codes¶

These error codes appear in HTTP error responses when a request is rejected.

Generic Errors¶

Error Code	HTTP Status	Title	Description
`validation_failed`	`400`	Validation failed	A required field is missing or has an invalid format
`bad_request`	`400`	Bad request	The request body is malformed or unreadable
`unauthorized`	`401`	Unauthorized	API key is missing or invalid
`not_found`	`404`	Not found	The requested resource does not exist
`business_logic_error`	`422`	Business logic error	A business rule was violated
`internal_server_error`	`500`	Internal server error	An unexpected server-side error occurred

Specific Validation Causes (HTTP 400)¶

These specific codes appear in the type URL while errorCode remains "validation_failed". Branch on type (or detail) when you need to handle them differently:

Specific Code (in `type`)	HTTP Status	Description
`config_unsupported_country`	`400`	Country is not supported
`config_unsupported_currency`	`400`	Currency is not supported for the payment method
`config_unsupported_payment_method`	`400`	Payment method is not available for your brand
`config_method_transaction_min_limit`	`400`	Amount is below the minimum allowed
`config_method_transaction_max_limit`	`400`	Amount exceeds the maximum allowed
`merchant_disabled`	`400`	Your merchant account is disabled

Specific Business Logic Causes (HTTP 422)¶

For 422 responses, errorCode carries the specific code directly (no separate type/errorCode split):

Error Code	HTTP Status	Description
`merchant_transactionid_duplicate`	`422`	Duplicate merchant reference

Asynchronous Transaction Error Codes¶

These error codes appear in the errorCode field of transaction objects after asynchronous processing (in callbacks and status check responses). They indicate why a transaction reached the failed status.

User Errors¶

Error Code	Description
`user_limit_exceeded`	End user exceeded daily/weekly/monthly limits
`user_insufficient_funds`	End user has insufficient funds
`user_authorization_failed`	Invalid PIN, OTP, or authorization
`user_account_block`	End user's account is blocked or restricted
`user_too_many_requests`	End user exceeded request rate limits
`user_cancelled`	End user cancelled the transaction
`user_timeout`	Timed out waiting for end user approval
`user_unknown_error`	Unspecified user-side error

Merchant Errors¶

Error Code	Description
`merchant_limit_exceeded`	Merchant limits exceeded
`merchant_transactionid_duplicate`	Duplicate transaction reference at provider level
`merchant_insufficient_funds`	Merchant wallet has insufficient funds
`merchant_invalid_credentials`	Invalid merchant credentials at provider
`merchant_cancelled_by_risk`	Transaction blocked by risk system
`merchant_unknown_error`	Unspecified merchant-side error

Provider Errors¶

Error Code	Description
`provider_limit_exceeded`	Provider daily/transaction limit exceeded
`provider_connection_error`	Connection to provider failed
`provider_too_many_requests`	Provider rate limited the request
`provider_cancelled`	Provider cancelled the transaction
`provider_unavailable`	Provider service is unavailable
`provider_transactionid_duplicate`	Duplicate transaction at provider level
`provider_timeout`	Provider did not respond in time
`provider_unknown_error`	Unspecified provider-side error
`provider_noresponse_from_method`	Payment method at provider not responding
`provider_wrong_configuration`	Provider configuration issue
`provider_bad_request`	Provider rejected the request

Configuration Errors¶

Error Code	Description
`config_unsupported_currency`	Currency not supported for this configuration
`config_unsupported_payment_method`	Payment method not supported for this configuration
`config_method_route_not_found`	No route found for the payment method
`config_method_transaction_min_limit`	Amount is below the minimum allowed
`config_method_transaction_max_limit`	Amount exceeds the maximum allowed

Security & Risk Errors¶

Error Code	Description
`security_authentication_failed`	Authentication failed at provider
`security_authorization_failed`	Authorization failed at provider
`risk_blocked`	Transaction blocked by risk/fraud rules
`gateway_too_many_requests`	Gateway-level rate limit reached

System Errors¶

Error Code	Description
`err500001`	Service temporarily unavailable
`err500002`	Request timeout
`transaction_expired`	Transaction expired before completion