Erros

Toda resposta de erro da API da CentralCart usa o mesmo envelope: um objeto com a chave errors, contendo um array.

{
  "errors": [
    { "message": "Cupom de desconto não encontrado." }
  ]
}

Campos

Campo	Tipo	Descrição
`message`	`string`	Mensagem legível, em português. Sempre presente.
`code`	`string`	Código semântico e estável do erro. Presente apenas em alguns erros. Veja abaixo.
`ref`	`string`	Identificador único desta ocorrência. Presente apenas em falhas de pagamento.

`code`

O code diz o que falhou, de forma estável e agrupável. Por exemplo, GATEWAY_CHARGE_FAILED. Hoje ele acompanha principalmente as falhas de geração de pagamento; a maior parte dos erros de validação vem apenas com message.

`ref`

O ref identifica qual ocorrência falhou, no formato MP-8061e7cd. Ele aparece em falhas de pagamento e é o valor que o comprador deve informar ao suporte. É por ele que a equipe localiza o erro exato nos registros.

{
  "errors": [
    {
      "message": "Não foi possível gerar o pagamento. Tente outro método.",
      "code": "GATEWAY_CHARGE_FAILED",
      "ref": "MP-8061e7cd"
    }
  ]
}

Se você exibe erros de checkout no seu front, mostre o ref quando ele vier. Sem ele, o suporte não tem como rastrear o caso.

Status HTTP

Status	Significado	O que fazer
`400`	Requisição malformada ou falha ao consultar um serviço externo.	Corrija a requisição. Não repita sem mudar nada.
`401`	Credencial ausente, inválida ou expirada.	Verifique a chave de API ou o token. Não repita.
`402`	Loja bloqueada.	Não repita. Fale com o suporte.
`403`	O recurso não pertence a esta loja, ou falta permissão.	Não repita.
`404`	Recurso não encontrado, inclusive loja não resolvida pelo `x-store-domain`.	Confira o identificador. Não repita.
`422`	Dados inválidos: campo obrigatório ausente, formato inválido, regra de negócio violada.	Corrija os dados e reenvie. A `message` diz qual campo falhou.
`429`	Limite de requisições atingido.	Respeite o header `Retry-After`. Veja Limites de requisição.
`500`	Erro interno.	Tente novamente com backoff exponencial. Se persistir, fale com o suporte.

{
  "errors": [
    {
      "message": "Resource rate limit reached.",
      "code": "RATE_LIMIT_REACHED"
    }
  ]
}

Múltiplos erros

errors é um array porque erros de validação podem trazer mais de uma entrada, uma por campo inválido. Trate sempre como lista.

{
  "errors": [
    { "message": "Informe um e-mail válido." },
    { "message": "Informe o seu nome completo." }
  ]
}

Tratando erros no cliente

async function request(path: string, init?: RequestInit) {
  const res = await fetch(`https://api.centralcart.io/v1${path}`, {
    ...init,
    headers: {
      'x-store-domain': 'sualoja.centralcart.ai',
      'Content-Type': 'application/json',
      ...init?.headers,
    },
  })

  if (res.ok) return res.json()

  const body = await res.json().catch(() => null)
  const first = body?.errors?.[0]

  throw Object.assign(new Error(first?.message ?? 'Erro inesperado.'), {
    status: res.status,
    code: first?.code,
    ref: first?.ref,
    retryAfter: Number(res.headers.get('Retry-After')) || undefined,
  })
}

Só faça retry automático em 429 e 500.

Documentação da API

Endpoints de aplicação

Storefront API (Public)

Campos

`code`

`ref`

Status HTTP

Múltiplos erros

Tratando erros no cliente

​Campos

​code

​ref

​Status HTTP

​Múltiplos erros

​Tratando erros no cliente

Campos

`code`

`ref`

Status HTTP

Múltiplos erros

Tratando erros no cliente