Payluk uses conventional HTTP status codes, and every response — including
errors — uses the standard envelope. On
an error, message carries the reason and data is an empty object.
{
"status": 400,
"message": "Action not allowed",
"data": {}
}
Status codes
| Code | Meaning |
|---|
200 | Success. |
201 | Resource created. |
400 | Validation failed, action not allowed in the current state, or not found. |
401 | Unauthorized — missing/invalid token, access denied, or a disallowed action. |
403 | Forbidden — feature not enabled, or wrong environment for the route. |
500 | Server error — e.g. an action attempted by an ineligible account type. |
Some validation and state errors that other APIs return as 403/404 are
reported here as 400 or 401 with a descriptive message. Always read
message rather than inferring meaning from the code alone.
Common messages
| Message | When it happens |
|---|
No token provided | Missing Authorization header. |
Access denied | The caller isn’t permitted to act on this resource. |
Action not allowed | The escrow isn’t in a state that permits this action. |
Escrow not found | No escrow matches the supplied token/ID. |
customer-id header is required | A customer-scoped route was called without the header. |
The sum of milestone amounts must equal the escrow amount | Milestone amounts don’t add up to amount. |
This feature is not enabled on your merchant account | The route needs a feature flag enabled on your account. |
This route is only available on staging environment | A staging-only helper was called on production. |
Handling errors
Because the HTTP code and status field always agree, you can branch on either.
A robust client checks status >= 400 and surfaces message to logs or to the
end user. 
