Request accepted
The API request was accepted. This does not necessarily mean that an asynchronous financial transaction has already reached its final state.
Error codes andAPI responses.
Pementek uses structured error responses so your integration can identify request problems, handle retries safely and respond appropriately to transaction conditions.
API errors describe problems with a request or operation. They are different from asynchronous transaction states such as VERIFYING orPENDING_RECONCILIATION.
Error response format
When an API operation cannot be completed normally, Pementek returns an HTTP status code together with a structured error object.
The error code is designed for programmatic handling, while the message provides a human-readable explanation. A request identifier may also be included to help with troubleshooting and support.
Example error response
{
"error": {
"code": "VALIDATION_ERROR",
"message": "The request contains invalid fields.",
"request_id": "req_01JABC123XYZ",
"details": [
{
"field": "amount",
"reason": "Amount must be greater than zero."
}
]
}
}HTTP status codes
Use both the HTTP status and the Pementek error code when deciding how your application should respond.
Request issue
The request could not be completed because of authentication, validation, state or other client-visible conditions.
Server issue
Pementek encountered a temporary or unexpected server-side condition. Safe retry behavior depends on the operation.
Pementek error codes
The following codes cover common integration and transaction request conditions. Additional product-specific codes may be documented as the platform evolves.
INVALID_REQUESTHTTP 400The request could not be processed because the request structure or payload is invalid.
Recommended action
Check the request body, headers and endpoint requirements before retrying.
VALIDATION_ERRORHTTP 400One or more request fields failed validation.
Recommended action
Review the error details and correct the invalid field values.
AUTHENTICATION_FAILEDHTTP 401The request could not be authenticated with the credentials provided.
Recommended action
Confirm that the API credential is valid and being sent correctly.
PERMISSION_DENIEDHTTP 403The authenticated account is not permitted to perform the requested operation.
Recommended action
Confirm that the account and environment have access to the requested capability.
TRANSACTION_NOT_FOUNDHTTP 404The requested payment, payout or transaction resource could not be found.
Recommended action
Confirm the transaction identifier and ensure you are using the correct environment.
IDEMPOTENCY_CONFLICTHTTP 409The supplied idempotency key was previously used with a different request.
Recommended action
Reuse an idempotency key only for retries of the same logical request.
TRANSACTION_STATE_CONFLICTHTTP 409The requested operation is not valid for the transaction in its current state.
Recommended action
Retrieve the latest transaction state before attempting another operation.
UNSUPPORTED_COUNTRYHTTP 422The requested country is not supported for the selected product or configuration.
Recommended action
Use a supported market or review current Pementek coverage.
UNSUPPORTED_CURRENCYHTTP 422The supplied currency is not supported for the requested transaction.
Recommended action
Use a currency supported for the selected country and payment flow.
UNSUPPORTED_PAYMENT_METHODHTTP 422The requested payment method is not available for the selected transaction.
Recommended action
Use a supported local payment method for the requested market.
ROUTING_UNAVAILABLEHTTP 422Pementek could not make a suitable transaction route available within the allowed routing window.
Recommended action
Do not assume payment success. You may create a new transaction when appropriate.
RATE_LIMITEDHTTP 429The client has exceeded the allowed request rate.
Recommended action
Reduce request frequency and retry using appropriate backoff.
TEMPORARILY_UNAVAILABLEHTTP 503The requested Pementek service is temporarily unavailable.
Recommended action
Retry safely using exponential backoff and the same idempotency key where applicable.
INTERNAL_ERRORHTTP 500An unexpected server-side error prevented the request from completing normally.
Recommended action
Retry only where appropriate. If the issue persists, contact Pementek support.
Transaction states are not API errors
A successful API request may create a transaction that still requires routing, customer action, verification or reconciliation before reaching a final result.
For example,WAITING_FOR_PROVIDER,VERIFYING andPENDING_RECONCILIATIONrepresent transaction lifecycle states rather than failed API requests.
Your application should retrieve the current transaction status or process signed webhook events rather than interpreting a verification delay as an API failure.
Safe retries
Retries are common in distributed payment systems, but they should be performed carefully to avoid accidentally creating duplicate financial operations.
When retrying a supported transaction creation request, reuse the same idempotency key for the same logical transaction request.
Never create a new idempotency key simply because the client did not receive a response to an earlier request. First determine whether the original request may already have been accepted.
Routing unavailable
If Pementek cannot make a suitable route available within the permitted routing window, the transaction may end with a routing-unavailable outcome.
The customer-facing experience should remain generic and should not expose internal provider availability, routing criteria or operational details.
A merchant may create a new transaction later where that is appropriate for the business flow.
Handling server errors
A 5xx response means the request could not be completed normally because of a Pementek-side or temporary service condition.
For retryable operations, use exponential backoff and preserve the original idempotency key where applicable.
If a transaction may already have been created, retrieve the transaction using your merchant reference or available transaction identifier before creating another request.
Need help with an error?
If an error persists or you need help understanding a transaction condition, contact Pementek and include the relevant request identifier, merchant reference and error code.
Do not send API secrets, passwords or private credentials in a support request.