Erros

A API usa códigos HTTP e devolve um objeto error com tipo, código e mensagem.

Formato do erro#

Respostas 2xx deram certo. 4xx indicam um problema na requisição. 5xx indicam uma falha do nosso lado.

Todo erro tem o mesmo formato. Trate o erro pelo code, que é estável. A message serve para depurar e pode mudar.

Campos do erro

error.typestring: Categoria do erro. Veja a lista abaixo.
error.codestring: Motivo específico, estável para tratar no seu código.
error.messagestring: Explicação em inglês para quem está depurando. Não trate o texto no código; ele pode mudar.
error.paramstring: Parâmetro que causou o erro, quando houver um.
error.request_idstring: ID da requisição. Também volta no header Request-Id. Envie ao suporte ao relatar um problema.

GET/v1/orders?limit=500

curl "https://api.movvio.com.br/v1/orders?limit=500" \
  -H "Authorization: Bearer mvk_live_xxx"

Resposta400 Bad Request

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "limit must not be greater than 100",
    "param": "limit",
    "request_id": "req_5f0c9a1b2d3e4f5a6b7c8d9e"
  }
}

Códigos#

Cada status HTTP tem um type. Dentro dele, o code diz o motivo.

Status, tipo e códigos

400invalid_request_error: parameter_invalid: valor fora da regra. parameter_unknown: parâmetro que o endpoint não aceita. invalid_cursor: cursor que a API não gerou.
401authentication_error: api_key_missing: sem header Authorization. api_key_invalid: chave inválida ou revogada (a resposta não diz qual).
403permission_error: insufficient_scope: a chave não tem o escopo do endpoint. browser_request_forbidden: a requisição veio de um navegador (tem header Origin).
404invalid_request_error: resource_missing: o recurso não existe, é de outra loja, ou o caminho não existe em /v1.
429rate_limit_error: rate_limited: limite de requisições excedido. Veja Rate limits.
500api_error: internal_error: falha do nosso lado. A mensagem é genérica; guarde o request_id.

Um parâmetro que o endpoint não conhece também é erro: a API responde 400 com parameter_unknown em vez de ignorar o parâmetro. Isso vale também para endpoints sem parâmetros, como GET /v1/store e GET /v1/orders/{id}. Com mais de um parâmetro desconhecido, param traz o primeiro.

Um caminho que não existe em /v1, ou um método que a rota não aceita, responde 404 com resource_missing, no mesmo formato.

Request-Id#

Toda resposta de erro traz o header Request-Id, com o mesmo valor de error.request_id. Registre esse valor nos seus logs e envie ao suporte quando relatar um problema.

Cache#

Toda resposta de /v1, de sucesso ou de erro, traz Cache-Control: no-store. Proxies e clientes HTTP não devem guardar as respostas: elas têm dados de clientes da loja.

Quando tentar de novo#

429 e 5xx: tente de novo depois de esperar. No 429, espere os segundos do header Retry-After.
400, 401, 403 e 404: não tente de novo sem corrigir a requisição ou a chave.