Errors returned by POST /v1/api/mozarto/checkout/session.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 brand JWT or user token |
403 Forbidden | Token valid but action not permitted (e.g. a company key used to create a session) |
404 Not Found | Route not enabled for your environment |
500 Internal Server Error | Unexpected server error - retry with backoff |
Authentication errors#
The Hosted page API uses the same headers as the Redirect API (see Authentication). A failed check returns 401 Unauthorized with a plain-text body, not JSON:| Body | Cause |
|---|
No token available, authorization denied! | Authorization header missing or not a Bearer token |
Invalid Token, authorization denied | Brand JWT invalid, or no brand matches its API key |
External user auth token is missing! | Neither x-user-token nor x-user-authorization is present |
"Failed to Complete the Authentication Check" | Unexpected error during the check (JSON string) |
Read the body as text before parsing it as JSON.
Session errors#
The body has no errorCode. Branch on the HTTP status and message:{
"status": "error",
"message": "country is required to resolve the payment configuration",
"isSuccess": false
}
| Status | message | Fix |
|---|
403 | Checkout sessions require a brand API key | Authenticate with a brand JWT, not a company JWT |
400 | country is required to resolve the payment configuration | Send country |
400 | Country not supported | Send a value from Country codes |
400 | currency is required as an ISO 4217 code, e.g. EUR | Send a three-letter currency code |
400 | returnUrls.<key> must be an https URL (http only for localhost) | Use https URLs in returnUrls |
400 | amount is incorrect | Send baseamount as a JSON number, not a string |
400 | No active payment page is configured for this brand and country | Activate a Payment Page for the country in the back office |
400 | PSP Configuration not found. Please check you psp Configuration | Configure a provider account whose Processing Scope covers the country and currency |
404 | Not Found (body: {"error":{"message":"Not Found","status":404}}) | The Hosted page API is not enabled in this environment - contact Mozarto |
Modified at 2026-10-29 16:47:06
