Errors
The Netzilo API answers every failed request with an HTTP status code and a short JSON body. This page lists what each code means, the messages worth recognizing, and the limits to design your scripts around.
The API has no version number in its path, and fields can change between releases. Test scripts that change or delete objects against a small group first.
Error body
{"message": "token invalid", "code": 401}
message is the reason in lowercase; match it case-insensitively. code repeats the
status code.
Status codes
- Name
2xx- Type
- Required
- optional
- Enum
- Description
The request succeeded.
- Name
400- Type
- Required
- optional
- Enum
- Description
The request is malformed, for example invalid JSON or an upload that is too large.
- Name
401- Type
- Required
- optional
- Enum
- Description
Authentication failed. The body always says
token invalid, whether the token is wrong, expired or deleted. See Authentication.
- Name
403- Type
- Required
- optional
- Enum
- Description
The token is valid, but its owner's role or the account's plan does not allow the request.
- Name
404- Type
- Required
- optional
- Enum
- Description
The object or the account does not exist.
- Name
409- Type
- Required
- optional
- Enum
- Description
A conflict: the name is already taken, or a plan limit was reached.
- Name
412- Type
- Required
- optional
- Enum
- Description
A precondition failed, for example a uniqueness rule, or a self-hosted server without its geolocation database.
- Name
422- Type
- Required
- optional
- Enum
- Description
A field failed validation, for example a required field is missing. Field errors are
422, not400.
- Name
500- Type
- Required
- optional
- Enum
- Description
An internal error. Deleting a group that is still in use also answers
500, see below.
Messages worth recognizing
| Message | Meaning |
|---|---|
token invalid | Any authentication failure. Create a new token rather than trying to tell the cases apart |
no valid authentication provided | The Authorization header is missing or unreadable |
| A message that the user has no access to the API or is blocked | The token's owner is blocked |
only users with admin power can perform this operation | The token's owner is not an admin |
maximum number of users reached | The Free plan's user limit |
maximum number of personal peers reached | The Free plan's device limit |
Deleting a group answers 500. The group is still used somewhere: in a policy, route,
DNS nameserver group, setup key, user, profile or filter, or as a disabled DNS management
group. Remove it from there, then delete the group.
Limits to design around
- No retries are safe by default. There is no idempotency key, and a repeated create can make a duplicate. Only group and nameserver group names are unique, so check before you create.
PUTreplaces the whole object. Read the object first, change it, and send all of it back.- Only
GET /api/events/paginatedpages its results. Every other list returns everything. Uselimit(1 to 1000) andoffset; alimitoutside that range is ignored and 25 is used instead, without an error. Bound event queries withdate_fromanddate_to. - Unknown query parameters are ignored, not rejected.
If you think you found a bug, write to support@netzilo.com with the request, the response and the time.

