Buscar na documentação

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluções

Erros e troubleshooting

Códigos de erro HTTP retornados pela API de Catálogo, diagnóstico de problemas comuns e boas práticas para integrações resilientes.

Códigos de erro HTTP

`400 Bad Request`

A requisição está malformada. Verifique:

Campos obrigatórios preenchidos.
Formato correto dos valores (datas em ISO 8601, preços como números).
IDs referenciados existem no sistema.
Corpo da requisição é JSON válido.

`401 Unauthorized`

O token expirou ou é inválido. Obtenha um novo accessToken e tente novamente. Veja Autenticação.

`403 Forbidden`

Você não tem permissão para a operação. Causas comuns:

Recurso exclusivo de outro vertical (ex.: preço por atacado em conta de restaurante).
Módulo não contratado para sua conta.
Tentativa de acessar dados de outra conta.

`404 Not Found`

O recurso não existe. Confirme que merchantId, catalogId, itemId e outros IDs estão corretos e que o recurso foi de fato criado.

`409 Conflict`

Recurso duplicado ou alteração incompatível. Exemplos:

externalCode já em uso por outro item.
Tentativa de mudar o tipo de um item para um valor incompatível com a categoria.

`413 Payload Too Large`

A requisição excedeu o limite de tamanho. Ocorre em:

Upload de imagem acima de 5 MB.
Lote com muitos itens.

Divida em requisições menores.

`422 Unprocessable Entity`

Os dados violam regras de negócio. Verifique:

Item tem price definido.
min de um grupo de complementos é menor ou igual a max.
A loja tem no máximo uma categoria do tipo PIZZA.
Categorias de pizza têm todos os grupos obrigatórios (SIZE, CRUST, EDGE, TOPPING).

`429 Too Many Requests`

Você excedeu o rate limit. Aguarde antes de repetir. Implemente backoff exponencial (veja boas práticas).

`500 Internal Server Error`

Erro no servidor iFood. Tente novamente em alguns minutos. Se persistir, abra um chamado com o batchId ou timestamp da chamada.

Diagnóstico de problemas comuns

Item não aparece no app

Verifique nesta ordem:

Item tem status: AVAILABLE
Categoria tem status: AVAILABLE
Item tem price.value definido
Cada grupo de complementos obrigatório tem pelo menos uma opção AVAILABLE
Disponibilidade por turno cobre a hora atual
Contexto de venda está correto

Consulte a resposta do endpoint de listagem de itens ou catálogo para confirmar que o item foi criado e seus atributos estão corretos.

Alterações de preço ou status não aparecem

Endpoints em lote rodam de forma assíncrona. Após chamar o endpoint:

Salve o batchId retornado
Consulte GET /batch/{batchId} a cada 5–10 segundos
Aguarde status: COMPLETED
Verifique result: SUCCESS para cada item em results

Se um item falhou, confirme que productId ou externalCode existe e que você tem permissão naquele contexto.

Erro ao criar pizza

Pizzas exigem esta estrutura:

Item com type: "PIZZA"
Omita categoryId (a API cria a categoria automaticamente)
Inclua os grupos SIZE, CRUST, EDGE e TOPPING
Cada grupo precisa de pelo menos uma opção com price definido

Exemplo de opção de tamanho:

{
  "id": "size-id",
  "status": "AVAILABLE",
  "productId": "size-product-id",
  "fractions": [1, 2],
  "externalCode": "size_code"
}

Veja o guia completo em Pizza.

`externalCode` duplicado

A API reutiliza produtos com o mesmo externalCode. Se você não quer reutilização, use códigos únicos. Se a reutilização é intencional (ex.: compartilhar um produto entre dois itens), mantenha o mesmo externalCode.

`contextModifiers` não surte efeito

Confirme:

catalogContext é um valor válido (DEFAULT, WHITELABEL, INDOOR).
contextModifiers é um array dentro da entidade (item ou opção).
O contexto existe no catálogo da loja.
Os valores em contextModifiers sobrescrevem os da raiz apenas no contexto especificado.

Imagem não aparece

Confirme:

Formato jpg, jpeg ou png.
Tamanho menor que 5 MB.
imagePath foi preenchido com o retorno do endpoint de upload.
O upload retornou 200 OK.

Boas práticas

Valide antes de ir para produção

Antes de ativar a integração:

Use o merchant de teste fornecido.
Teste cada fluxo (criar, atualizar, pausar, deletar).
Valide com GET /catalogs/{catalogId}/categories?include_items=true para confirmar que itens e complementos foram criados corretamente.

Use `externalCode` para rastreabilidade

Inclua um externalCode único em cada item e complemento. Você consegue:

Atualizar recursos usando seu próprio ID
Rastrear mudanças originadas no seu sistema
Fazer sincronização bidirecional sem depender de IDs do iFood

Implemente retry com backoff exponencial

Para operações sujeitas a falhas transitórias (5xx, 429, timeouts):

Tentativa	Espera
1	Imediata
2	1 s
3	2 s
4	4 s

Não tente novamente em 4xx (exceto 429) — o problema é no payload, não no servidor.

Monitore operações em lote

Não assuma que um lote terminou pelo retorno imediato:

Salve o batchId
Consulte GET /batch/{batchId} até status: COMPLETED
Registre falhas individuais em results

{
  "batchId": "batch-123",
  "status": "COMPLETED",
  "results": [
    { "resourceId": "item-1", "result": "SUCCESS" },
    { "resourceId": "item-2", "result": "FAILURE" }
  ]
}

Use `contextModifiers` em vez de duplicar itens

Crie o item uma vez e ajuste preço, status e código por contexto. Duplicar itens por canal dificulta manutenção e causa divergências.

Registre chamadas e respostas

Armazene para cada operação:

Timestamp
Endpoint e método
Payload enviado
Resposta recebida (incluindo batchId)

Esses registros são essenciais para debug e para abrir chamados no suporte.

Suporte

Se o problema persistir, abra um chamado no Suporte do Developer Portal com:

merchantId afetado.
Endpoint e método chamados.
IDs dos recursos envolvidos.
Resposta de erro completa.
Timestamp da chamada.

Esta página foi útil?

Avalie sua experiência no novo Developer portal:

Erros e troubleshooting

Códigos de erro HTTP

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

413 Payload Too Large

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error