Erros

Todo erro da API vem com o tipo application/problem+json (RFC 9457) e um código estável em code. Decida pelo code (e pelo status HTTP), nunca pelo texto de detail, que é para pessoas e pode mudar.

{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "este plano está indisponível no momento neste local",
  "code": "cloud.out_of_stock",
  "request_id": "6f1c0b2a9e4d7c3b5a8f0e1d"
}

Campo	Sempre	O que é
type	sim	Sempre about:blank.
title	sim	O texto padrão do status HTTP (Bad Request, Not Found…).
status	sim	O status HTTP, repetido no corpo.
code	sim	Código estável, como validation_failed ou cloud.out_of_stock.
detail	não	A mensagem em português, pronta para mostrar a uma pessoa.
errors	não	O motivo de cada campo, em validation_failed e request.invalid_json: {"hostname": "obrigatório"}.
existing_id	não	Num conflito com um registro que já existe, o id dele: em cloud.external_id_taken, o servidor que já tem o external_id.
request_id	não	O mesmo valor do cabeçalho X-Request-ID. Informe ao suporte quando abrir um chamado.

Códigos por status

A lista traz os códigos que a API pública devolve hoje. Um código novo pode aparecer: trate pelo status HTTP o que não conhece e mostre o detail.

400 Requisição inválida

Código	Quando	O que fazer
validation_failed	Um campo ou parâmetro não passou na validação	Corrija os campos listados em errors
request.invalid_json	JSON malformado, campo desconhecido ou de tipo errado	Confira o corpo contra a referência
request.empty_body	A operação pede corpo e ele veio vazio	Mande o corpo
request.invalid_id	Um id do caminho não é UUID	Use o id devolvido pela API
request.invalid_query	Um parâmetro de consulta inválido	Confira o parâmetro
invalid_cursor	O cursor não é o next_cursor desta lista	Use o next_cursor da página anterior (Paginação)
idempotency.invalid_key	Idempotency-Key fora do formato	De 1 a 255 caracteres ASCII visíveis, como um UUID (Idempotência)

401 Não autenticado

Código	Quando	O que fazer
auth.unauthorized	Token ausente, inválido, expirado, revogado ou de outro ambiente. Vem com WWW-Authenticate: Bearer error="invalid_token"	Crie um token novo ou confira o cabeçalho Authorization

403 Sem permissão

Código	Quando	O que fazer
api_token.insufficient_scope	O token não tem o escopo da operação (indicado em WWW-Authenticate: Bearer error="insufficient_scope", scope="…"), ou o papel da pessoa não permite mais	Crie um token com o escopo (Autenticação e escopos)
api_token.route_not_allowed	A operação não aceita token (cartões, pagamento, tokens, firewalls)	Use o painel

404 Não encontrado

<recurso>.not_found: o recurso não existe ou não é da sua conta. Os códigos são server.not_found, operation.not_found, ssh_key.not_found, private_network.not_found, private_network_server.not_found, elastic_ip.not_found, console_session.not_found, console_transcript.not_found, ipmi_vpn_session.not_found, invoice.not_found, receipt.not_found e ticket.not_found.

Depois de uma remoção, GET /cloud/servers/{id} responde 404 server.not_found.

409 Conflito

Algo em andamento impede a operação agora. Espere e tente de novo.

Código	Quando
cloud.server_busy, cloud.operation_running	Há uma operação em andamento no servidor (deploy, reinstalação, limpeza ou remoção)
cloud.payment_pending	O pagamento da contratação ainda está em confirmação
cloud.server_suspended	O servidor está desligado por falta de pagamento: energia, reinstalação, apagar, cancelar e VPN da IPMI esperam a fatura ser paga
cloud.server_unavailable, cloud.server_deleting, cloud.server_deleted	O servidor aguarda pagamento, teve a assinatura cancelada ou já foi removido
cloud.server_empty	O servidor já está sem sistema
cloud.cancel_scheduled, cloud.cancel_not_scheduled	O cancelamento já está agendado, ou não há cancelamento para desfazer
cloud.ssh_key_exists	A chave SSH já está cadastrada
cloud.external_id_taken	Outro servidor da conta (não removido) já tem este external_id; o id dele vem em existing_id
cloud.console_open, cloud.console_connecting, cloud.console_closed	Já há uma sessão de console aberta no servidor, ela ainda está conectando, ou não está mais aberta
cloud.vpn_session_open	Já há uma sessão de VPN da IPMI aberta no servidor
cloud.private_network_in_use, cloud.private_network_deleting	Tire os servidores da rede antes de apagá-la; a rede já está sendo apagada
cloud.elastic_ip_busy, cloud.elastic_ip_releasing	Uma mudança no IP elástico está em andamento, ou ele já está sendo liberado
cloud.elastic_ips_unavailable, cloud.private_networks_unavailable	O recurso não está disponível na região (veja GET /cloud/network)
cloud.network_busy	Duas mudanças de rede ao mesmo tempo: tente de novo
support.ticket_merged, support.ticket_purged	O chamado foi juntado a outro, ou a conversa foi apagada pelo prazo de guarda
idempotency.in_progress	A primeira requisição com a mesma Idempotency-Key ainda roda: repita depois do Retry-After

422 Regra de negócio

A requisição é válida, mas uma regra impede.

Código	Quando
cloud.payment_method_required	A conta não tem cartão salvo: cadastre um no painel antes de contratar
cloud.payment_refused	O cartão recusou a primeira fatura
cloud.out_of_stock	O plano está indisponível no momento neste local
cloud.unavailable	O plano ou o local não está disponível
coupon.unavailable	O cupom não vale (sem dizer o motivo)
cloud.quota_exceeded	A conta chegou a uma cota (Limites de uso)
cloud.user_data_unsupported	O sistema escolhido não roda cloud-init (User data)
cloud.immediate_release_disabled	release=immediate não está liberado para a conta
cloud.unpaid_invoices	Há fatura em aberto do período em uso: a liberação imediata não perdoa dívida
cloud.console_unavailable	O servidor não pode abrir o console agora (estado, suspensão)
cloud.vpn_unavailable, cloud.vpn_full	A VPN da IPMI não está disponível na região, ou todas as sessões dela estão em uso
cloud.other_region	O servidor e o recurso de rede são de regiões diferentes
cloud.no_free_address, cloud.no_private_space, cloud.private_network_full	Não há IP elástico livre, espaço para uma rede nova ou endereço livre na rede
invoice.not_paid	O comprovante só existe para fatura paga
idempotency.key_reused	A Idempotency-Key já foi usada com outra requisição: gere uma nova

429 Limite de requisições

Código	Quando
rate_limited	Passou do limite do token ou de uma operação. Espere o Retry-After
coupon.rate_limited	Muitas tentativas de cupom
cloud.console_rate_limited	Digitação rápida demais no console serial

Veja Limites de uso.

503 Indisponível

Uma dependência não respondeu. Tente de novo com espera crescente (por exemplo 1, 2, 4 e 8 segundos).

Código	Quando
request.timeout	A operação demorou demais
cloud.power_failed, cloud.boot_device_failed	A IPMI do servidor não respondeu
cloud.console_failed, cloud.console_unavailable	O console serial não abriu
idempotency.unavailable	Não foi possível registrar ou ler a Idempotency-Key

Num POST que cobra (contratar um servidor ou um IP elástico), um 503 não quer dizer que nada aconteceu: a falha pode vir depois da cobrança. Repetir a mesma Idempotency-Key devolve o mesmo 503, porque a resposta fica guardada. Confira o recurso com um GET antes de tentar de novo com uma chave nova. Já num erro de rede, sem resposta nenhuma, repita com a mesma chave. Veja Idempotência.