API requests, responses and errors
Send a request
Section titled “Send a request”Send each call as a POST to /api/<role>/<module>/<call> with the parameters as a JSON object and
the Content-Type: application/json header. Form fields work too. A call without parameters takes
{}. Parameter names are the ones in the API reference.
curl --silent --user "admin:$CLIENTFENCE_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"id": 42}' \ https://billing.example.com/api/admin/invoice/getBody JSON that cannot be read answers Malformed JSON input with the reason.
Read the answer
Section titled “Read the answer”Every answer is a JSON object with two fields:
{ "result": { "id": 42, "status": "unpaid", "total": 25.5 }, "error": null }result: what the call returns (an object, a list,true, an id). The reference describes it for each call.error:nullwhen the call worked, otherwise an object withmessageandcode.
Errors
Section titled “Errors”{ "result": null, "error": { "message": "Invoice not found", "code": 9999 } }Always check error: many errors answer with HTTP status 200. An error without a code of its own has
code 9999. These codes set the HTTP status:
| HTTP status | Codes | Meaning |
|---|---|---|
| 401 | 201-206 | Authentication Failed: no key, a wrong key or a wrong user name. See Authentication. |
| 401 | 1002 | Unauthorized IP: the key is used from an address not on the API key access list. |
| 403 | 403 | A missing permission, a wrong CSRF token, or an action the account may not do. |
| 404 | 740 | The call does not exist in that module and role. |
| 200 | 715 | The module is not installed or not active. |
| 400 | 701, 879 | The URL is not an API call (a wrong role or path). |
| 429 | 429 | Rate limit exceeded. Wait the seconds in the Retry-After header. See Rate limits. |
| 503 | 503 | An update is waiting to be finalized. |
Other errors explain the problem in message (a missing parameter, an invalid value, a record not
found) and answer HTTP 200. Show message to the person using your integration or log it. For client
and guest calls, an unexpected server error answers An unexpected error occurred. Please try again later. and the details go to the logs (System Activity and the
files under data/log/).
Paged lists
Section titled “Paged lists”Calls that list records (most get_list calls) return one page at a time:
| Parameter | Default | |
|---|---|---|
page |
1 | The page number, from 1. |
per_page |
100 | Rows per page, 1 to 500. A larger number is an error. |
{ "pages": 3, "page": 1, "per_page": 100, "total": 245, "list": [ { "id": 1 }, { "id": 2 } ] }An empty object, such as a record’s config or translations with nothing in it, comes back as an
empty list [], so treat [] and {} alike.
total is the number of rows over all pages and pages the number of pages. Ask for the next page
until it is greater than pages. Each call’s filters (status, client, dates) are in the reference.
Dates and amounts
Section titled “Dates and amounts”- Dates and times are strings like
2026-11-17 09:30:00, in the time zone of the billing server. - In list filters and statistics,
date_toincludes that whole day:2026-11-17also finds records from 23:00 that day. A date ClientFence cannot read, in a filter or in an order, invoice or promotion date, is refused with Enter a valid date. The API log list ignores it instead. - Amounts are numbers, such as
25.5, in the currency of the record: an invoice’scurrencyfield, or the client’s currency. They are not formatted and carry no currency sign. - Ids are numbers. Yes/no values are
true/falseor1/0, as the reference says for each call.
Rate limits
Section titled “Rate limits”| Calls | Limit |
|---|---|
| Admin and client calls | 1,000 an hour for each account when signed in with a session; 1,000 an hour for each address otherwise, such as with an API key |
| Guest calls | 100 a minute for each address |
Failed sign-in calls (staff/login, client/login and passkey sign-in) |
10 an hour for each address |
Some guest calls have lower limits of their own, such as sign-up, domain search, promo codes and
invoice links. Over a limit the call answers code 429 with a Retry-After header. Requests from the
addresses in Never rate limited (Security → Settings → Access lists) skip every limit: add your
integration server there. See Proxies, access lists and sessions. Every limit, and how to reset one, is on
Rate limits.

