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.

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, not 400.

  • 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

MessageMeaning
token invalidAny authentication failure. Create a new token rather than trying to tell the cases apart
no valid authentication providedThe Authorization header is missing or unreadable
A message that the user has no access to the API or is blockedThe token's owner is blocked
only users with admin power can perform this operationThe token's owner is not an admin
maximum number of users reachedThe Free plan's user limit
maximum number of personal peers reachedThe 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.
  • PUT replaces the whole object. Read the object first, change it, and send all of it back.
  • Only GET /api/events/paginated pages its results. Every other list returns everything. Use limit (1 to 1000) and offset; a limit outside that range is ignored and 25 is used instead, without an error. Bound event queries with date_from and date_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.

Was this page helpful?

© Copyright 2026. All rights reserved.