Skip to main content
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 codeMeaning
200Request completed successfully
201Resource created successfully
400Bad request
401Authentication failed
403Permission denied
404Resource not found
409Duplicate or conflicting request
422Validation error
429Too many requests
500Server error

​
Common error codes

CodeMeaning
authentication_failedThe API key is missing, invalid, or inactive
invalid_requestThe request body is malformed or missing required fields
validation_errorOne or more fields failed validation
resource_not_foundThe requested resource does not exist
duplicate_requestThe idempotency key or transaction reference has already been used
insufficient_balanceThe merchant does not have enough balance for the request
transaction_failedThe transaction could not be completed
rate_limit_exceededToo many requests were sent in a short period
server_errorAn unexpected server error occurred

​
Validation error example

{
  "status": false,
  "message": "The amount field is required.",
  "code": "validation_error",
  "errors": {
    "amount": [
      "The amount field is required."
    ]
  }
}

​
How to handle errors

1

Check the status code

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

Read the error code

Use the code field for app logic and retry decisions.
3

Show a helpful message

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

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.