Erros e recuperação

Use códigos de erro estáveis para decidir entre corrigir, aguardar ou tentar novamente.

O que fazer

Baseie a lógica no estado HTTP e em error.code, não no texto de error.message.
Um 401 exige autenticação válida; um 403 exige mudanças de acesso ou plano; um 409 exige verificar a operação em conflito ou a versão do recurso.

Acesso negado e novas tentativas

401: 401 nem sempre significa que o token expirou. Se expirou, obtenha outro e repita a leitura no máximo uma vez. Se a solicitação do token retornar 401, verifique a chave e interrompa as tentativas automáticas.
403: Em caso de 403, verifique as permissões, as restrições de IP e o plano. Um novo token não restaura um acesso revogado.

Autenticação

Política de novas tentativas

Limite as tentativas de falhas transitórias e aplique esperas progressivas com variação aleatória.
Respeite Retry-After quando presente.
Se uma escrita exceder o tempo de espera, o resultado pode ser desconhecido: preserve o mesmo Idempotency-Key e a requisição sem alterações ao repetir essa operação lógica.
O catálogo abaixo explica todos os códigos de erro publicados.

Escritas seguras

Limites de requisições

422 / 409

Para preços, um formato de moeda ou uma precisão do valor inválidos retornam 422 request.validation_failed.
Um código de moeda válido que não corresponde à tabela de preços selecionada retorna 409 resource.version_conflict.
Confira o contexto e as versões antes de tentar novamente.

Catálogo de erros

400request.malformedNão foi possível interpretar a requisição.

O que fazer: Verifique a sintaxe JSON, a codificação da URL e a estrutura da requisição.
Política de novas tentativas: Tente novamente após corrigir a requisição.

JSON

{
  "error": {
    "code": "request.malformed",
    "fields": null,
    "message": "The request could not be read."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.invalid_credentialsA chave API ou o token de acesso é inválido, expirou ou foi revogado.

O que fazer: Verifique a URL da loja e a credencial. Obtenha um novo token com uma chave API ativa.
Política de novas tentativas: Tente novamente após corrigir a autenticação; evite requisições repetidas de tokens inválidos.

JSON

{
  "error": {
    "code": "authentication.invalid_credentials",
    "fields": null,
    "message": "The credentials are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.requiredO cabeçalho Authorization obrigatório está ausente ou seu esquema está incorreto.

O que fazer: Use ApiKey ao solicitar um token e Bearer nas operações de recursos.
Política de novas tentativas: Tente novamente após fornecer o cabeçalho correto.

JSON

{
  "error": {
    "code": "authentication.required",
    "fields": null,
    "message": "Authentication is required."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.client_ip_unverifiedO serviço não conseguiu determinar um endereço IP de cliente confiável.

O que fazer: Peça ao operador da loja que verifique o caminho de entrada. Não insira cabeçalhos de encaminhamento por conta própria.
Política de novas tentativas: Tente novamente após restabelecer o caminho de conexão confiável.

JSON

{
  "error": {
    "code": "authorization.client_ip_unverified",
    "fields": null,
    "message": "The client IP address could not be verified."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.ip_not_allowedO IP de origem não está na lista de endereços permitidos da chave.

O que fazer: Use um endereço de origem aprovado ou peça a um administrador autorizado que edite a lista IP da chave.
Política de novas tentativas: Tente novamente somente depois que o endereço for permitido.

JSON

{
  "error": {
    "code": "authorization.ip_not_allowed",
    "fields": null,
    "message": "Access from this IP address is not allowed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.scope_deniedA chave não possui uma permissão efetiva exigida por esta operação.

O que fazer: Verifique as permissões obrigatórias e condicionais da operação, as concessões da chave e o acesso de quem a emitiu.
Política de novas tentativas: Tente novamente após um administrador autorizado conceder o acesso necessário.

JSON

{
  "error": {
    "code": "authorization.scope_denied",
    "fields": null,
    "message": "The required permission has not been granted."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.api_disabledO acesso API está desabilitado para esta loja.

O que fazer: Peça ao proprietário que verifique o plano ativo e a disponibilidade da API.
Política de novas tentativas: Não tente novamente até que o acesso API seja habilitado.

JSON

{
  "error": {
    "code": "entitlements.api_disabled",
    "fields": null,
    "message": "API access is disabled for this store."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.limit_exceededA alteração ultrapassaria um limite do plano atual.

O que fazer: Verifique o limite aplicável ao recurso e ajuste a alteração pretendida ou o plano.
Política de novas tentativas: Tente novamente após resolver o limite; use outra chave de idempotência se a requisição mudar.

JSON

{
  "error": {
    "code": "entitlements.limit_exceeded",
    "fields": null,
    "message": "The operation exceeds a plan limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.operation_disabledO plano atual não inclui esta operação.

O que fazer: Verifique o plano mínimo apresentado para a operação.
Política de novas tentativas: Tente novamente quando o plano permitir a operação e a chave tiver as permissões necessárias.

JSON

{
  "error": {
    "code": "entitlements.operation_disabled",
    "fields": null,
    "message": "The current plan does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.resource_blockedUm limite do plano bloqueia este recurso específico.

O que fazer: Peça ao proprietário que resolva a restrição do plano sobre o recurso.
Política de novas tentativas: Não repita a mesma requisição enquanto o recurso continuar bloqueado.

JSON

{
  "error": {
    "code": "entitlements.resource_blocked",
    "fields": null,
    "message": "A plan limit blocks access to this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

404resource.not_foundO recurso está ausente, foi excluído ou não está disponível com o identificador informado.

O que fazer: Verifique a loja, o caminho e o identificador do recurso. Use identificadores retornados por esta loja.
Política de novas tentativas: Tente novamente somente após corrigir o destino ou confirmar sua existência.

JSON

{
  "error": {
    "code": "resource.not_found",
    "fields": null,
    "message": "The resource was not found."
  },
  "meta": {
    "request_id": "example-request"
  }
}

405request.method_not_allowedO endpoint não aceita este método HTTP.

O que fazer: Use o método documentado; o cabeçalho Allow identifica os métodos aceitos.
Política de novas tentativas: Não tente novamente com o método não aceito.

JSON

{
  "error": {
    "code": "request.method_not_allowed",
    "fields": null,
    "message": "This method is not supported for this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409idempotency.key_reusedEsta chave de idempotência pertence a outra requisição.

O que fazer: Localize a operação original. Use uma chave nova somente para uma operação lógica nova e intencional.
Política de novas tentativas: Não repita um conteúdo alterado com a chave em conflito.

JSON

{
  "error": {
    "code": "idempotency.key_reused",
    "fields": null,
    "message": "This idempotency key was used with a different request."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.already_existsUm valor único entra em conflito com um recurso existente.

O que fazer: Leia o recurso existente e decida se deve usá-lo ou escolher outro valor único.
Política de novas tentativas: Não repita a mesma criação em conflito.

JSON

{
  "error": {
    "code": "resource.already_exists",
    "fields": null,
    "message": "A resource with these unique values already exists."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.in_useOutros recursos ainda dependem deste recurso.

O que fazer: Revise as dependências e remova-as ou altere-as por operações aceitas antes de excluir.
Política de novas tentativas: Tente novamente após resolver as dependências.

JSON

{
  "error": {
    "code": "resource.in_use",
    "fields": null,
    "message": "The resource is still in use."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.state_conflictO estado de negócio atual impede esta alteração.

O que fazer: Leia o estado atual e escolha uma transição de negócio válida.
Política de novas tentativas: Não force automaticamente nem envie repetidamente a alteração em conflito.

JSON

{
  "error": {
    "code": "resource.state_conflict",
    "fields": null,
    "message": "The current resource state does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.version_conflictOutra escrita alterou o recurso depois da versão que você leu.

O que fazer: Leia o estado mais recente, concilie a alteração e envie o novo expected_version.
Política de novas tentativas: Use uma nova chave de idempotência para a operação revisada; não sobrescreva sem verificar.

JSON

{
  "error": {
    "code": "resource.version_conflict",
    "fields": null,
    "message": "The resource version has changed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

413request.too_largeA requisição ultrapassa o limite de tamanho.

O que fazer: Reduza o conteúdo ou divida o trabalho em operações individuais aceitas.
Política de novas tentativas: Tente novamente com operações válidas menores e suas próprias chaves de idempotência.

JSON

{
  "error": {
    "code": "request.too_large",
    "fields": null,
    "message": "The request exceeds the size limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

415request.unsupported_media_typeO tipo de mídia ou a codificação do conteúdo não é aceito.

O que fazer: Nas escritas JSON use Content-Type: application/json e um corpo aceito sem compressão.
Política de novas tentativas: Tente novamente após corrigir o tipo de mídia ou a codificação.

JSON

{
  "error": {
    "code": "request.unsupported_media_type",
    "fields": null,
    "message": "The request media type or encoding is not supported."
  },
  "meta": {
    "request_id": "example-request"
  }
}

422request.validation_failedUm ou mais campos ou parâmetros não passaram na validação.

O que fazer: Consulte error.fields e verifique campos obrigatórios, aceitação de null, identificadores e valores permitidos.
Política de novas tentativas: Tente novamente com uma requisição corrigida; uma escrita alterada é uma nova operação lógica.

JSON

{
  "error": {
    "code": "request.validation_failed",
    "fields": null,
    "message": "Some request parameters are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.queue_fullA fila curta da API está cheia; a execução da solicitação não começou.

O que fazer: Coloque as requisições em fila e respeite o cabeçalho de resposta Retry-After.
Política de novas tentativas: Aguarde pelo menos os segundos de Retry-After e acrescente variação aleatória. Preserve a chave e o conteúdo originais ao repetir uma escrita.

JSON

{
  "error": {
    "code": "capacity.queue_full",
    "fields": null,
    "message": "The API is busy. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.wait_timeoutO tempo de espera na fila da API acabou; a execução da solicitação não começou.

O que fazer: Coloque as requisições em fila e respeite o cabeçalho de resposta Retry-After.
Política de novas tentativas: Aguarde pelo menos os segundos de Retry-After e acrescente variação aleatória. Preserve a chave e o conteúdo originais ao repetir uma escrita.

JSON

{
  "error": {
    "code": "capacity.wait_timeout",
    "fields": null,
    "message": "The API could not start this request in time. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429rate_limit.exceededA frequência de requisições ultrapassa o limite aplicável.

O que fazer: Coloque as requisições em fila e respeite o cabeçalho de resposta Retry-After.
Política de novas tentativas: Aguarde pelo menos os segundos de Retry-After e acrescente variação aleatória. Preserve a chave e o conteúdo originais ao repetir uma escrita.

JSON

{
  "error": {
    "code": "rate_limit.exceeded",
    "fields": null,
    "message": "The request rate limit has been exceeded."
  },
  "meta": {
    "request_id": "example-request"
  }
}

500internal.errorOcorreu um erro inesperado no serviço.

O que fazer: Registre o identificador da requisição e contate o operador se o erro persistir; exclua credenciais dos logs.
Política de novas tentativas: Limite as tentativas e aumente a espera. Nas escritas preserve a chave de idempotência original e o conteúdo inalterado.

JSON

{
  "error": {
    "code": "internal.error",
    "fields": null,
    "message": "An unexpected error occurred."
  },
  "meta": {
    "request_id": "example-request"
  }
}

502gateway.bad_responseO gateway não recebeu uma resposta API válida.

O que fazer: Preserve o identificador da requisição. Uma resposta com falha não prova que a escrita não foi aplicada.
Política de novas tentativas: Limite as tentativas e aumente a espera; repita a mesma escrita lógica com seu Idempotency-Key e conteúdo originais.

JSON

{
  "error": {
    "code": "gateway.bad_response",
    "fields": null,
    "message": "The API gateway could not obtain a valid response."
  },
  "meta": {
    "request_id": "example-request"
  }
}

503service.unavailableA API está temporariamente impossibilitada de atender à requisição.

O que fazer: Respeite Retry-After quando presente e preserve o identificador da requisição se a indisponibilidade persistir.
Política de novas tentativas: Limite as tentativas com esperas progressivas e variação aleatória; preserve a chave e o conteúdo ao repetir a mesma escrita.

JSON

{
  "error": {
    "code": "service.unavailable",
    "fields": null,
    "message": "The API is temporarily unavailable."
  },
  "meta": {
    "request_id": "example-request"
  }
}

504gateway.timeoutO gateway excedeu o tempo de espera da API.

O que fazer: Preserve o identificador da requisição e considere desconhecido o resultado da escrita.
Política de novas tentativas: Limite as tentativas e aumente a espera; nas escritas reutilize a chave de idempotência original e o conteúdo inalterado.

JSON

{
  "error": {
    "code": "gateway.timeout",
    "fields": null,
    "message": "The API gateway timed out."
  },
  "meta": {
    "request_id": "example-request"
  }
}