Tratamento de códigos de erro da API

Ao integrar a API do Cord, vale a pena tratar bem as respostas com falha para oferecer uma boa experiência.

Estrutura de um erro

As respostas com falha retornam um objeto JSON simples com dois campos:

{
  "error": "Company name is required",
  "code": "invalid_request"
}

• error: mensagem legível que você pode exibir ou registrar.
• code: identificador estável para ramificar no seu código (p. ex. invalid_json, invalid_request).

Códigos HTTP comuns

• 400 Bad Request: falta um parâmetro ou o JSON está malformado (code: "invalid_request" ou "invalid_json").
• 401 Unauthorized: a sua chave de API é inválida, foi revogada ou você não enviou o header Authorization ("invalid_key", "missing_key"), ou a chave expirou ("key_expired").
• 402 Payment Required: a sua assinatura atingiu o número de chaves de API incluídas no plano ("subscription_key_limit"); revogue uma chave anterior ou mude para um plano superior.
• 403 Forbidden: a sua chave não tem o escopo necessário (p. ex. você usa uma chave somente leitura para um POST, código "insufficient_scope"), uma chave restrita não tem permissão para esse recurso ("insufficient_permissions"), a chave tem IPs permitidos e a requisição veio de outro ("ip_not_allowed"), ou uma chave publicável tenta usar uma origem/domínio não autorizado ("unauthorized_origin", "missing_origin").
• 404 Not Found: o recurso não existe ou não pertence à sua organização.
• 409 Conflict: a ação não se encaixa no status atual do recurso — por exemplo, cancelar uma fatura que já tem pagamentos aplicados responde 409 com code: "credit_note_required": o documento correto é uma nota de crédito.
• 413/415: o corpo da requisição excede o limite de tamanho ("payload_too_large") ou não vem como application/json ("unsupported_media_type").
• 429 Too Many Requests: você ultrapassou o limite de requisições ou a cota mensal do seu plano ("api_quota_exceeded"). Veja Limites de requisições.
• 500 Internal Server Error: erro do nosso lado (raro; fale com o suporte se persistir).
• 502/503: o provedor externo do qual a operação depende não respondeu — por exemplo, timbrar uma fatura sem conseguir comprovar a taxa de câmbio responde 503 com code: "fx_unavailable" em vez de inventar uma taxa (veja a política de taxa de câmbio na documentação de faturamento).

Nota: a API v1 não processa cobranças com cartão diretamente; isso acontece no link público do Cord. Por isso, você não verá erros de cartão recusado nessas respostas.