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.

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.

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.

4. 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#

PSP configuration not found - 400#

Provider returned an error - 400#

Retry guidance#