Errors
Failures are predictable. Every error carries an HTTP status you can branch on and a JSON body
with a detail field describing what went wrong.
Error shape
Most errors return a single human-readable message in detail:
response · 409 Conflict
{
"detail": "Domínio já cadastrado"
}Branch on the status, not the message
detail messages are human-readable (currently in Portuguese) and may change or be
localized. Branch your logic on the HTTP status and the endpoint — treat detail as text to surface to a developer, not as a machine contract.Validation errors
When the request body fails schema validation the status is 422 and detail is an array pinpointing each offending field:
response · 422 Unprocessable Content
{
"detail": [
{
"loc": ["body", "ttl"],
"msg": "Input should be greater than or equal to 60",
"type": "greater_than_equal"
}
]
}Domain-rule violations also use 422, but with a single message. Two common ones
when creating records:
response · 422 · plan limit reached
{
"detail": "Limite do plano Free atingido (500 registros por organização). Faça upgrade para criar mais registros."
}response · 422 · CNAME conflict
{
"detail": "CNAME não pode coexistir com outros records no mesmo nome"
}Status reference
| Status | Name | Meaning |
|---|---|---|
| 401 | Unauthorized | Missing, malformed or invalid credentials — e.g. "Não autenticado" or "Token inválido ou expirado". |
| 403 | Forbidden | Authenticated, but not allowed: unverified e-mail when creating zones ("Verifique seu e-mail antes de adicionar zonas") or missing role ("Requer papel admin ou owner"). |
| 404 | Not Found | Resource does not exist in your organization — "Zona não encontrada", "Record não encontrado", "Organização não encontrada". Also returned for resources that belong to another organization. |
| 409 | Conflict | Conflicting state — "Domínio já cadastrado", "DNSSEC já está habilitado nesta zona", "DNSSEC não está habilitado nesta zona". |
| 422 | Unprocessable Content | The request is well-formed but invalid: schema validation (detail is an array), record content rules, CNAME coexistence, plan limits, missing DNSSEC confirmation. |
| 502 | Bad Gateway | The authoritative DNS backend rejected the operation. Nothing was persisted — safe to retry. |
Retrying safely
502 means the DNS backend refused the operation before anything was persisted —
it is safe to retry with backoff. 4xx errors are yours to fix: retrying the same
request will fail the same way.