API reference

Error handling

Every failure comes back in the same envelope: type: "error", data: [], and the reasons as an array of strings in message.error with the HTTP status repeated in message.code. One error branch handles the whole API.

Common failures

400validationA field failed validation — e.g. "The amount must be a string." when amount is sent as a number. The array may hold several messages, one per failing field. Fix the request; don’t retry it unchanged.

400invalid secret"Invalid secret ID" from the token endpoint — the secret_id is wrong or was regenerated. Re-copy both keys from the merchant panel.

403invalid token"Requested with invalid token!" — the Bearer access token is expired (they live 600 seconds) or wrong. Request a fresh access token and retry once; a second 403 means a credential problem, not expiry.

404wrong base URLThe route doesn’t exist — usually a mistyped base URL. It must end in /pay/api/v1; the response here may be the platform’s HTML 404 rather than the JSON envelope.

5xxserver errorTransient failure on the Fu-Lu side. Retry with exponential backoff (e.g. 1s, 2s, 4s, then give up). Token requests are safe to repeat; for payment/create, keep your own order reference so a retry can’t double-charge.

Surfacing errors

Log the full message.error array (plus the endpoint and message.code) — it’s written for you, the developer.
Don’t show those strings to customers. "Invalid secret ID" means nothing to a buyer and leaks integration detail — show a generic “payment couldn’t be started, please try again” instead.
Branch on type (or the HTTP status) before reading data — on errors it’s an empty array, not an object.

Retry rules of thumb

400 — never retry unchanged; fix the request.
403 — refresh the token, retry once.
5xx — retry with backoff, a few attempts at most.

Error 400 · validation

{
  "message": {
    "code": 400,
    "error": ["The amount must be a string."]
  },
  "data": [],
  "type": "error"
}

Error 400 · invalid secret

{
  "message": {
    "code": 400,
    "error": ["Invalid secret ID"]
  },
  "data": [],
  "type": "error"
}

Error 403 · invalid token

{
  "message": {
    "code": 403,
    "error": ["Requested with invalid token!"]
  },
  "data": [],
  "type": "error"
}