Entender é tratar os erros da API

A API pública CaptainDNS retorna todos os seus erros em um envelope JSON padronizado. Esta página lista os códigos canonicos, seu significado é a ação corretiva recomendada.

Envelope padrao

Toda resposta de erro segue este formato:

{
  "code": "QUOTA_EXCEEDED",
  "message": "Monthly credits quota exceeded for plan 'starter'.",
  "details": {
    "tier": "starter",
    "credits_used": 50000,
    "credits_limit": 50000
  },
  "request_id": "req_a1b2c3d4",
  "documentation_url": "https://www.captaindns.com/en/docs/api/errors"
}

• code: string estavel documentada aqui. Use-a para ramificar sua logica de tratamento de erros.
• message: descricao legivel em ingles. Não faca parse; ela pode evoluir.
• details: objeto opcional com contexto especifico do código. Seu esquema varia por código. A maioria dos códigos não expoe details: a informação é entao carregada pelo message.
• request_id: identificador CaptainDNS da requisicao, útil para abrir um ticket de suporte. Presente somente se o header X-Request-Id foi propagado.
• documentation_url: link para esta página.

O status HTTP sempre acompanha o código. Um cliente robusto ramifica no par (status, code) é trata code como prioridade.

Códigos de autenticação (401)

INVALID_API_KEY

Status: 401.

Causa: header Authorization ausente, prefixo ausente, chave malformada, segredo alterado ou chave não encontrada pelo CaptainDNS. Um HMAC mismatch é uma "chave desconhecida" retornam o mesmo código para não distinguir um do outro para um atacante.

Acao: verifique que o header é bem Authorization: Bearer cdns_live_.... Um espaço parasita, uma quebra de linha ou uma chave truncada sao as causas mais frequentes.

{
  "code": "INVALID_API_KEY",
  "message": "Invalid API key.",
  "request_id": "req_a1b2c3d4",
  "documentation_url": "https://www.captaindns.com/en/docs/api/errors"
}

Sem campo details; a informação esta somente em message.

EXPIRED_API_KEY

Status: 401.

Causa: a chave ultrapassou seu expires_at.

{
  "code": "EXPIRED_API_KEY",
  "message": "This API key has expired.",
  "request_id": "req_a1b2c3d4",
  "documentation_url": "https://www.captaindns.com/en/docs/api/errors"
}

Sem campo details.

Acao: crie uma nova chave com uma data de expiracao mais distante ou sem expiracao. As chaves sem expires_at sao validas enquanto não forem revogadas.

REVOKED_API_KEY

Status: 401.

Causa: a chave foi revogada manualmente ou automaticamente (fim da grace period de rotação).

{
  "code": "REVOKED_API_KEY",
  "message": "This API key has been revoked.",
  "request_id": "req_a1b2c3d4",
  "documentation_url": "https://www.captaindns.com/en/docs/api/errors"
}

Sem campo details.

Acao: use a chave ativa. Se não tiver nenhuma, crie uma no dashboard.

Códigos de autorizacao (403)

INSUFFICIENT_SCOPE

Status: 403.

Causa: a chave não tem o escopo necessário para o endpoint. O escopo ausente é concatenado em message.

{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This API key does not have the required scope: web:read",
  "request_id": "req_a1b2c3d4",
  "documentation_url": "https://www.captaindns.com/en/docs/api/errors"
}

Sem campo details; o escopo necessário é lido a partir de message.

Acao: crie uma nova chave com o escopo ausente ou use uma chave que já o carregue. Os escopos não podem ser modificados apos a criacao.

IP_NOT_ALLOWED

Status: 403.

Causa: a chave tem uma allowlist de IP é o IP da requisicao não faz parte dela. O IP do cliente é derivado de r.RemoteAddr no backend (nunca de um X-Forwarded-For enviado pelo cliente), apos eventual reescrita pela camada TrustedProxyRealIP se o hop imediato é um proxy de confiança configurado no lado CaptainDNS.

{
  "code": "IP_NOT_ALLOWED",
  "message": "Your IP is not in this key's allowlist.",
  "request_id": "req_a1b2c3d4",
  "documentation_url": "https://www.captaindns.com/en/docs/api/errors"
}

Sem campo details; o IP detectado é a lista CIDR não sao devolvidos ao cliente (sao registrados no servidor).

Acao: adicione seu IP a allowlist da chave, ou roteie seu tráfego por um egress autorizado (proxy, NAT).

QUOTA_EXCEEDED

Status: 403.

Causa: a cota mensal de créditos foi atingida é o plano não permite excedente (plano Free, hard cap).

{
  "code": "QUOTA_EXCEEDED",
  "message": "Monthly credits quota exceeded for plan 'free'.",
  "details": {
    "tier": "free",
    "credits_used": 500,
    "credits_limit": 500
  },
  "request_id": "req_a1b2c3d4",
  "documentation_url": "https://www.captaindns.com/en/docs/api/errors"
}

Acao: aguarde o proximo período ou passe ao plano superior. O dashboard CaptainDNS permite trocar de plano em um clique.

OVERAGE_BUDGET_EXCEEDED

Status: 403.

Causa: o perfil ativou o excedente mas atingiu o teto orcamentario mensal configurado no dashboard. As chamadas seguintes sao recusadas até o fim do período ou até que o teto seja elevado.

{
  "code": "OVERAGE_BUDGET_EXCEEDED",
  "message": "Overage budget cap reached for plan 'starter'.",
  "details": {
    "tier": "starter",
    "credits_used": 68000,
    "credits_limit": 50000
  },
  "request_id": "req_a1b2c3d4",
  "documentation_url": "https://www.captaindns.com/en/docs/api/errors"
}

Acao: eleve o teto em Account > API usage, passe a um plano com envelope maior ou aguarde o proximo período mensal.

Códigos de requisicao (400)

INVALID_REQUEST

Status: 400.

Causa: um componente da requisicao não pode ser processado. Dois casos sao emitidos pela API pública:

• Header Idempotency-Key malformado (caracteres não ASCII, espacos, tamanho fora dos limites, valor vazio apos trim).
• Body da requisicao ilegivel ou excedendo o limite de idempotência (11 MiB).

{
  "code": "INVALID_REQUEST",
  "message": "Invalid Idempotency-Key header.",
  "request_id": "req_a1b2c3d4",
  "documentation_url": "https://www.captaindns.com/en/docs/api/errors"
}

Sem campo details; o motivo preciso esta em message.

Acao: corrija o header ou o body é tente novamente. Para erros de validacao especificos de um endpoint (dominio invalido, selector desconhecido, etc.), consulte a secao Códigos de validacao (400).

Códigos de conflito (409)

IDEMPOTENCY_CONFLICT

Status: 409.

Causa: uma chave Idempotency-Key é reutilizada com um body diferente da requisicao original. A comparacao é feita no hash SHA-256 do body bruto.

{
  "code": "IDEMPOTENCY_CONFLICT",
  "message": "Idempotency-Key reused with a different request body.",
  "request_id": "req_a1b2c3d4",
  "documentation_url": "https://www.captaindns.com/en/docs/api/errors"
}

Sem campo details; a chave conflitante é aquela que você acabou de enviar.

Acao: gere uma nova chave para a nova requisicao, ou corrija o cliente que modifica o body entre os retries.

Códigos de rate limit (429)

RATE_LIMITED

Status: 429.

Causa: o token bucket por chave esta vazio ou o limite por IP foi ultrapassado. Duas variantes de message conforme a camada atingida:

• Bucket IP pré-auth: "Too many requests from this IP. Slow down.".
• Bucket por chave: "Rate limit exceeded for this API key.".

{
  "code": "RATE_LIMITED",
  "message": "Rate limit exceeded for this API key.",
  "request_id": "req_a1b2c3d4",
  "documentation_url": "https://www.captaindns.com/en/docs/api/errors"
}

Sem campo details. O header Retry-After sempre acompanha este código, expresso em segundos. Aguarde pelo menos essa duração antes de tentar novamente. Veja o guia de rate limiting para as estrategias de backoff.

Códigos de servidor (5xx)

INTERNAL_ERROR

Status: 500 ou 503.

Causa: erro inesperado no lado CaptainDNS. Duas variantes:

• 500: erro aplicativo transitório (panic em handler, dependência de DB indisponível, erro de lookup de tier, etc.). A message detalha o subsistema.
• 503: a API pública não esta configurada ou o group /public/v1/* foi explicitamente desativado na plataforma (pepper ausente, flag PUBLICAPI_ENABLED=false). Não existe código SERVICE_UNAVAILABLE distinto: a indisponibilidade compartilha o código INTERNAL_ERROR com status 503.

{
  "code": "INTERNAL_ERROR",
  "message": "public api is not configured",
  "request_id": "req_a1b2c3d4"
}

Sem campo details.

Acao: guarde o request_id é abra um ticket de suporte. Os 503 geralmente estao ligados a uma manutencao planejada ou a um incidente: consulte o canal de status oficial antes de tentar novamente. Tente novamente apos alguns minutos para os 500 transitórios; se a taxa ultrapassar 1 % em uma janela de cinco minutos, alerte a equipe CaptainDNS.

Códigos de validacao (400)

A API também retorna 400 BAD_REQUEST para erros de validacao especificos de cada endpoint. Esses erros não sao cobertos pelo envelope padronizado acima pois sua estrutura varia por endpoint.

Exemplo para um DNS resolve com dominio invalido:

{
  "error": "invalid domain: must be a valid FQDN",
  "field": "domain"
}

Para os endpoints que retornam erros de validacao, consulte a referência OpenAPI que documenta os esquemas exatos.

Tabela sintetica

Boas praticas de tratamento

• Ramifique no par (status, code). O status sozinho não basta: dois 403 podem vir de INSUFFICIENT_SCOPE ou de IP_NOT_ALLOWED, que merecem ações diferentes.
• Registre o request_id. É o identificador unico da requisicao no lado CaptainDNS é é necessário para qualquer investigação no suporte.
• Não tente novamente cegamente. Os 4xx exceto 429 indicam um problema no cliente: tentar sem mudar nada não vai funcionar.
• Respeite Retry-After. Os 429 é 503 sempre o incluem. Não o ignore.
• Alerte sobre taxas de erro. 1 % de 5xx em uma janela de 5 minutos é um sinal de incidente. Eleve isso na sua observabilidade.

Siga para a referência OpenAPI para explorar os esquemas endpoint por endpoint, ou volte ao quickstart se quiser recomeçar do inicio.