Errors

HTTP status codes

Code	Meaning
`200 OK`	Request succeeded
`400 Bad Request`	Invalid request body - missing required field or validation failure
`401 Unauthorized`	Missing or invalid Bearer token
`403 Forbidden`	Token valid but action not permitted (e.g. password expired)
`500 Internal Server Error`	Unexpected server error - retry with backoff

Error response format

All errors return a consistent JSON body:

{
  "status": "error",
  "message": "Error description",
  "isSuccess": false,
  "errors": ["Specific validation error"]
}

Field	Type	Description
`status`	string	Always `"error"` for error responses
`message`	string	Human-readable description of the problem
`isSuccess`	boolean	Always `false` for error responses
`errors`	array	List of specific error messages (may be empty)

Common errors

Missing required field - 400

{
  "status": "error",
  "message": "Missing required field: pspType",
  "isSuccess": false,
  "errors": []
}

Check the PSP reference page for required fields.

Validation failed - 400

{
  "status": "error",
  "message": "Validation failed",
  "isSuccess": false,
  "errors": [
    "amount must not be empty",
    "email must be a valid email"
  ]
}

Invalid token - 401

{
  "status": "error",
  "message": "Unauthorized",
  "isSuccess": false,
  "errors": []
}

Verify the Bearer token is present and has not expired.

Orchestration rule not configured - 400

{
  "status": "error",
  "message": "Rules action is not matched",
  "isSuccess": false,
  "errors": []
}

No active Orchestration rule exists for your company and the selected PSP. Go to Orchestration in the back office, create a rule that matches your company (or sub-brand) and the pspType you are using, and ensure the rule is active before retrying.

Orchestration rule condition not met - 400

{
  "status": "error",
  "message": "Error",
  "isSuccess": false,
  "errors": [
    "Amount should be greater than 100. Current value is 11."
  ]
}

A matching Orchestration rule exists but the request does not satisfy its conditions - for example, the transaction amount is outside the configured min/max range. The errors array contains the specific constraint that failed. Adjust the request to meet the rule's conditions, or update the rule in the back office under Orchestration.

PSP configuration not found - 400

{
  "status": "error",
  "message": "Something went wrong",
  "isSuccess": false,
  "data": "PSP Configuration not found. Please check you psp Configuration"
}

The payment provider is not configured for your company in the Mozarto back office. Go to Payment Methods - Configuration, select the provider, and save the required credentials (username, password, webhook URL, and any provider-specific fields) under your company before retrying.

Provider returned an error - 400

{
  "status": "error",
  "message": "Payment provider rejected the request",
  "isSuccess": false,
  "errors": ["Invalid currency for selected provider"]
}

The request reached the payment provider but was rejected. Check the errors array for the provider's reason.

PSP-specific error responses

Each provider returns rejection details in a different shape inside the data field. The message field always contains a human-readable description; data carries the raw provider payload.

Worldpay

Worldpay errors return a numeric errorCode and a human-readable errorMessage in data:

{
  "status": "error",
  "message": "Something went wrong",
  "isSuccess": false,
  "data": {
    "errorCode": "5",
    "errorMessage": "Invalid card details",
    "transactionId": "64a1f2b3c4d5e6f7a8b9c0d1"
  }
}

Field	Description
`data.errorCode`	Numeric error code from Worldpay - use for programmatic handling
`data.errorMessage`	Human-readable description of the rejection
`data.transactionId`	Mozarto transaction ID - use to look up the failed transaction

ForumPay

ForumPay errors include an err string and an err_code identifier in data. Some errors also include an additional object with provider-specific metadata:

{
  "status": "error",
  "message": "Invoice amount is too high.",
  "isSuccess": false,
  "data": {
    "err": "Invoice amount is too high.",
    "err_code": "amountExceedsTransactionLimit",
    "additional": {
      "limit": "8486.30",
      "invoice_currency": "EUR"
    },
    "transactionId": "64a1f2b3c4d5e6f7a8b9c0d1"
  }
}

Field	Description
`data.err`	Human-readable error string from ForumPay
`data.err_code`	Machine-readable error code from ForumPay - use this for programmatic handling
`data.additional`	Optional object with provider-specific context (e.g. transaction limits, currency). Present on some errors only
`data.transactionId`	Mozarto transaction ID - use to look up the failed transaction

ForumPay Pay-Out errors follow the same structure. err_code values are camelCase strings defined by ForumPay (e.g. amountExceedsTransactionLimit). The additional field is not guaranteed on every error - check for its presence before accessing its properties.

PayOne

PayOne errors return a single error string in data. There is no separate error code field:

{
  "status": "error",
  "message": "Invalid account details",
  "isSuccess": false,
  "data": {
    "error": "Invalid account details"
  }
}

Field	Description
`data.error`	Error string returned directly from PayOne

The message field mirrors data.error. Use data.error for display or logging — there is no machine-readable code to branch on.

Gigadat

Gigadat errors use the standard top-level errors array. There is no provider-specific data field:

{
  "status": "error",
  "message": "Error",
  "isSuccess": false,
  "errors": [
    "Amount should be greater than 12. Current value is 10."
  ]
}

Field	Description
`errors`	Array of validation or rejection strings returned by Gigadat - may contain one or more messages
`message`	Always `"Error"` for Gigadat rejections - use `errors[0]` for the specific reason

Gigadat Pay-Out (ETO and ACH) returns the same error shape. The errors array always contains at least one message.

For 500 responses, Gigadat returns data as a string with the provider's error detail rather than null:

{
  "status": "error",
  "message": "Internal server error",
  "isSuccess": false,
  "data": "CPI Payload validation failed: Mobile must be 10 digits (5551234567) or 11 digits with country code (15551234567)"
}

Read data as a string when handling Gigadat 500 responses.

ForumPay Pay-Out - on hold (not an error)

A successful ForumPay Pay-Out returns 200 OK with transaction_status: "On Hold", not an error response. The pay-out is held for admin approval before processing:

{
  "status": "success",
  "message": "Transaction is on hold",
  "isSuccess": true,
  "data": {
    "invoice_currency": "EUR",
    "invoice_amount": "13.00",
    "currency": "BTC",
    "payment_source": "cash",
    "wait_time": "20 minutes",
    "network_processing_fee": "0.00000735",
    "rate": "68899.7244",
    "amount_exchange": "0.00018868",
    "amount": 13,
    "fast_transaction_fee": "0.00001044",
    "fast_transaction_fee_currency": "BTC/kB",
    "payment_id": "1a52f405-5652-4fb6-b37f-538e1feb24d0",
    "reference_no": "6a01ed09b681e530b9f26584",
    "address": "btc-1eda64a85da94d71a2ac5ed84e929553",
    "access_token": "<forumpay-access-token>",
    "transactionId": "6a01ed09b681e530b9f26584",
    "merchantReference": ""
  }
}

Do not treat this as a failure. Wait for the webhook with a terminal transaction_status before crediting or debiting the user.

Retry guidance

Retry only when the failure is likely transient. Retrying a request with invalid data can create noise and slow down recovery.

When retrying 500 errors, use exponential backoff (for example: 1s, 2s, 4s, 8s; cap at 30s) and stop after a small number of attempts.

5. Errors

Errors#

HTTP status codes#

Error response format#

Common errors#

Missing required field - 400#

Validation failed - 400#

Invalid token - 401#

Orchestration rule not configured - 400#

Orchestration rule condition not met - 400#

PSP configuration not found - 400#

Provider returned an error - 400#

PSP-specific error responses#

Worldpay#

ForumPay#

PayOne#

Gigadat#

ForumPay Pay-Out - on hold (not an error)#

Retry guidance#