---
title: Errors and pitfalls
slug: errors-and-pitfalls
createdAt: 2026-11-02T08:43:03.181Z
---

## Two error models

|                  | Legacy                                                                                                                                                                                                                 | Cloud Panel                                                                                                                                                                                                            |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Transport status | Often <font color="#EF4444">`200`</font> even on failure                                                                                                                                                               | Meaningful HTTP status                                                                                                                                                                                                 |
| Error signal     | <font color="#EF4444">`code` </font>field in the body                                                                                                                                                                  | HTTP status + JSON body                                                                                                                                                                                                |
| Business codes   | <font color="#EF4444">`406`</font>, <font color="#EF4444">`409`</font>, <font color="#EF4444">`412`</font>, <font color="#EF4444">`416`</font>, <font color="#EF4444">`417`</font>, <font color="#EF4444">`428`</font> | <font color="#EF4444">`400`</font>, <font color="#EF4444">`401`</font>, <font color="#EF4444">`403`</font>, <font color="#EF4444">`404`</font>, <font color="#EF4444">`409`</font>, <font color="#EF4444">`422`</font> |
| Batch results    | —                                                                                                                                                                                                                      | <font color="#EF4444">`207`</font> with <font color="#EF4444">`successes`</font>/ <font color="#EF4444">`errors`</font>                                                                                                |

Legacy example — HTTP 200 carrying a business failure:

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

## Checklist of things that break integrations

- **Using the wrong key on the wrong host.** <font color="#EF4444">`X-API-KEY`</font> is legacy-only; <font color="#EF4444">`x-api-key`</font> / Bearer are Cloud-only. A <font color="#EF4444">`401`</font> almost always means a swapped key.
- **Treating&#x20;**<font color="#EF4444">`customer_code`</font>**&#x20;as&#x20;**<font color="#EF4444">`organizationId`</font>**.** Integer vs UUID; the call may even succeed against a different tenant if IDs collide — always take the UUID from <font color="#EF4444">`/customerarea/customers/list`</font>.
- **Assuming&#x20;**<font color="#EF4444">`organization_id`</font>**&#x20;is immediately available.** It is <font color="#EF4444">`null`</font> until the tenant is provisioned/migrated. Poll, don't fail.
- **Ignoring&#x20;**<font color="#EF4444">`207`</font>**.** Batch category/TLD operations can partially succeed. Read <font color="#EF4444">`errors[]`</font> and retry only the failed items.
- **Creating a network without binding a policy.** The network exists but filters nothing. Always call <font color="#EF4444">`POST /network/v1/{networkId}/policies`</font> and verify with <font color="#EF4444">`GET .../policies`</font>.
- **Reusing a&#x20;**<font color="#EF4444">`dnsId`</font>**&#x20;already taken.** Use <font color="#EF4444">`/network/v1/{networkId}/dns/available`</font>; 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 (<font color="#EF4444">`412 You can't insert internal IPs`</font>). Use the public WAN address.
- **Assuming legacy profile semantics.** A legacy <font color="#EF4444">`profile_code`</font> 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 <font color="#EF4444">`refreshToken`</font> or, for server-to-server, the <font color="#EF4444">`x-api-key`</font> to avoid refresh logic entirely.
- **Locale-dependent catalogues.** Always pass <font color="#EF4444">`lang`</font> to catalogue endpoints; names are localized but **IDs are stable** — store IDs, not names.

## Status codes you will actually see

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