Errors - Payluk API

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.