Errors and pitfalls

3 min

Two error models

Legacy example — HTTP 200 carrying a business failure:

{
  "code": 409,
  "content": "Please provide a valid customer"
}

Using the wrong key on the wrong host. X-API-KEY is legacy-only; x-api-key / Bearer are Cloud-only. A 401 almost always means a swapped key.

Treating customer_code as organizationId. Integer vs UUID; the call may even succeed against a different tenant if IDs collide — always take the UUID from /customerarea/customers/list.

Assuming organization_id is immediately available. It is null until the tenant is provisioned/migrated. Poll, don't fail.

Ignoring 207. Batch category/TLD operations can partially succeed. Read errors[] and retry only the failed items.

Creating a network without binding a policy. The network exists but filters nothing. Always call POST /network/v1/{networkId}/policies and verify with GET .../policies.

Reusing a dnsId already taken. Use /network/v1/{networkId}/dns/available; a resolver already bound to another policy on the same network will be rejected.

Reusing an IP across platforms. The same public IP cannot be configured on the legacy and the new platform at the same time. If a tenant migrates, remove the IP from the legacy network first, then create it on the new one.

LAN addresses. Static single/range endpoints reject private/internal IPs (412 You can't insert internal IPs). Use the public WAN address.

Assuming legacy profile semantics. A legacy profile_code has no counterpart on the new platform: policies must be rebuilt (use templates to speed this up).

Rate limits. None are enforced today, but they are planned to be tied to the purchased license. Design with conservative pacing and retry/backoff from day one.

Token expiry. JWT access tokens are short-lived; use refreshToken or, for server-to-server, the x-api-key to avoid refresh logic entirely.

Locale-dependent catalogues. Always pass lang to catalogue endpoints; names are localized but IDs are stable — store IDs, not names.

Code	Where	Meaning
200	Both	Success
201	Cloud	Resource created
207	Cloud	Partial success on a batch — inspect successes/ errors
400	Cloud	Malformed body
401	Both	Missing/invalid credentials
403	Both	Authenticated but not allowed (role or ownership)
404	Cloud	Unknown ID, or ID outside your organization context
406	Legacy	Business rule violated (e.g. profile not found, network already exists)
409	Legacy	Conflict (e-mail registered, profile not found)
412	Legacy	Precondition failed (internal IP, default profile deletion)
416	Legacy	Range exceeds the allowed size
422	Both	Validation error with field details
428	Legacy	Role does not permit the operation