Errors

Pasteaza uses standard HTTP status codes and consistent error responses so you can understand what went wrong and handle failures in your application.

Always check the HTTP status code first. Then use the error code field for programmatic handling.

Error response format

{
  "status": false,
  "message": "Invalid API key.",
  "code": "authentication_failed"
}

Common HTTP status codes

Status code	Meaning
`200`	Request completed successfully
`201`	Resource created successfully
`400`	Bad request or validation error
`401`	Authentication failed
`403`	Permission denied
`404`	Resource not found
`409`	Duplicate or conflicting request
`429`	Too many requests
`500`	Server error

Common error codes

Code	Meaning
`authentication_failed`	The API key is missing, invalid, or inactive.
`validation_failed`	One or more required fields are missing or invalid. Validation errors usually return HTTP `400` in the current API.
`invalid_test_bank`	The supplied test bank code is invalid. In test mode, use the supported test bank code.
`recipient_not_found`	The supplied `recipientCode` was not found for the authenticated merchant and environment.
`insufficient_balance`	The merchant does not have enough available balance for the transfer.
`transfer_not_found`	The requested transfer reference was not found.
`virtual_account_not_found`	The requested virtual account reference was not found.
`provider_incomplete_response`	The upstream provider returned incomplete virtual account details.
`provider_request_failed`	The upstream provider request failed.

Validation error example

{
  "status": false,
  "message": "amount must be a positive integer.",
  "code": "validation_failed"
}

How to handle errors

Check the status code

Use the HTTP status code to decide whether the request failed because of authentication, validation, permission, or server issues.

Read the error code

Use the code field for app logic and retry decisions.

Show a helpful message

Use the message field to display a friendly explanation to the user.

Retry safely

Retry only safe requests or requests that include an Idempotency-Key.

Best practices

Log the status code, error code, and request reference when a request fails.
Do not expose raw server messages to end users without context.
Retry only when the request is safe to repeat.
Use idempotency for create and payout requests.
Contact support if you repeatedly receive server_error responses.

Next step

After you understand errors, continue with webhooks so you can verify asynchronous updates from Pasteaza.

Getting Started

Collections

Disbursements

Error response format

Common HTTP status codes

Common error codes

Validation error example

How to handle errors

Best practices

Next step

​Error response format

​Common HTTP status codes

​Common error codes

​Validation error example

​How to handle errors

​Best practices

​Next step

Error response format

Common HTTP status codes

Common error codes

Validation error example

How to handle errors

Best practices

Next step