Erros

Toda falha volta no mesmo envelope. O code é estável e é o que o seu sistema deve tratar; a message é para pessoas e pode mudar.

{
  "error": {
    "type": "validation_error",
    "code": "validation_failed",
    "message": "Confira os dados enviados.",
    "errors": [
      {
        "param": "name",
        "message": "não pode ficar em branco"
      }
    ],
    "request_id": "c0a8f2e1-…"
  }
}

type agrupa o erro; param e errors aparecem quando há um campo específico. Novos campos podem ser acrescentados — ignore os que você não conhece.

HTTP	code	O que fazer
400	`api_key_in_url`	Envie a chave só no cabeçalho Authorization.
400	`malformed_json`	Corrija o JSON enviado.
400	`invalid_request`	Confira os parâmetros obrigatórios.
400	`idempotency_key_required`	Envie o cabeçalho Idempotency-Key no cadastro de cliente.
400	`invalid_idempotency_key`	Use uma chave de idempotência com até 255 caracteres.
400	`invalid_pagination`	Use limit entre 1 e 100 e um cursor recebido da própria API.
401	`invalid_api_key`	Confira a chave; se foi revogada, peça uma nova.
403	`api_not_enabled`	A API ainda não foi habilitada para a empresa.
403	`api_suspended`	O acesso à API está suspenso; fale com o Loy.
403	`account_inactive`	A assinatura da empresa no Loy não está ativa.
403	`insufficient_scope`	A chave não tem o escopo exigido pelo endpoint.
404	`not_found`	O recurso não existe nesta empresa.
404	`customer_not_found`	O customer_id da visita não existe nesta empresa.
404	`service_not_found`	O service_id da visita não existe nesta empresa.
404	`reward_not_found`	Nenhuma recompensa com esse código nesta empresa; confira com o cliente.
409	`reward_already_redeemed`	A recompensa já foi utilizada; não entregue de novo.
422	`reward_expired`	A recompensa venceu e não pode mais ser utilizada.
409	`webhook_endpoint_limit_reached`	Remova um endereço de webhook antes de cadastrar outro.
422	`invalid_webhook_url`	Use um endereço https:// público.
503	`webhooks_unavailable`	Os webhooks ainda não estão disponíveis; tente mais tarde.
409	`customer_email_taken`	Já existe cliente com este e-mail; busque-o com GET /customers?email=.
409	`customer_external_id_taken`	Já existe cliente com este external_id; busque-o com GET /customers?external_id=.
409	`idempotency_key_in_use`	Outra requisição com a mesma chave está em andamento; tente de novo em instantes.
422	`idempotency_key_reused`	A chave já foi usada com outro conteúdo; gere uma chave nova.
422	`validation_failed`	Confira o campo errors: cada item traz param e message.
429	`rate_limited`	Espere o tempo de Retry-After e tente de novo.
429	`concurrency_limited`	Reduza as requisições simultâneas.
429	`quota_exceeded`	Quota do mês atingida; fale com o Loy.
500	`internal_error`	Tente de novo com espera; se persistir, envie o request_id.
503	`api_unavailable`	A API está temporariamente indisponível.

Códigos de novos endpoints são listados na referência e em Novidades.

O acesso é liberado pela equipe do Loy. Pedir acesso.