Erros

401: token ausente ou inválido

{
  "error": {
    "name": "NotAuthorizedError",
    "message": "Invalid authorization token"
  }
}

Confira se o header se chama exatamente Api-Token e se o token é do ambiente certo (homologação e produção têm tokens diferentes). Confira também se a requisição não leva um header Authorization: quando ele está presente, a API usa o valor dele no lugar do Api-Token e responde 401. Veja Autenticação.

400: dados inválidos

O corpo do erro 400 depende de onde a requisição foi barrada.

Campo ausente ou com tipo errado. Antes de chegar à regra de negócio, a API confere se os campos obrigatórios existem e têm o tipo certo. O erro lista cada campo com problema:

{
  "name": "ValidationError",
  "errors": [
    { "name": "bodyPropertyError: cpf", "message": "Propriedade inválida: cpf." },
    { "name": "bodyPropertyError: products", "message": "Propriedade obrigatória não encontrada: products." }
  ]
}

O name de cada item traz o lugar (bodyPropertyError, paramsPropertyError ou queryPropertyError) e o nome do campo.

Regra de negócio nas rotas de venda. Em criar checkout e nas consultas de venda, as regras de negócio devolvem SALE-001:

{
  "name": "ValidationError",
  "errors": [
    { "name": "SALE-001", "message": "The checkoutPriceInCents cannot be bigger than the totalAmount of products" }
  ]
}

message descreve o problema. Casos comuns:

Demais erros. Nas outras rotas, e nas regras do cadastro automático de produto e variação em POST /sales, o erro vem no formato { "error": { "name", "message" } }, com name padronizado e message descrevendo o problema (às vezes em português):

{
  "error": {
    "name": "BodyPropertyError",
    "message": "Curso já existe."
  }
}

404: rota inexistente

Um caminho que não existe devolve 404 com HTML (Cannot GET /checkout/v4/...), não JSON. Se você receber HTML, confira a URL base e o caminho da rota em Ambientes.

Recursos não encontrados

Rotas que buscam por ID (curso, turma, campanha, venda exclusiva) devolvem 404 em JSON quando o registro não é encontrado. A exceção são as consultas de venda (GET /sales/purchase/{saleId} e GET /sales/external-purchase/{externalSaleId}), que devolvem 400 com Sale not found. Os exemplos de cada rota estão nas Rotas da API.