Buscar en la documentación

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluciones

Errores y Troubleshooting

Códigos de error

La API retorna diferentes códigos de estado HTTP para indicar el resultado de una solicitud. A continuación están los códigos principales encontrados y cómo tratarlos:

Código	Descripción	Solución
`204 No Content`	Operación realizada exitosamente	Ninguna acción necesaria
`400 Bad Request`	Solicitud malformada o parámetros inválidos	Verifique la sintaxis de la solicitud y los valores de los parámetros
`401 Unauthorized`	Token JWT ausente o inválido	Verifique si el token está presente y es válido
`404 Not Found`	Pedido o ítem no encontrado	Confirme si el `id` o `uniqueId` es correcto
`409 Conflict`	Conflicto al ejecutar la operación	Verifique las validaciones listadas para cada endpoint
`500 Internal Server Error`	Error interno del servidor	Intente de nuevo. Si el error persiste, contacte con soporte

Escenarios comunes de error

Error `404 Not Found` al iniciar la separación

Mensaje: Order not foundCausas:

ID de pedido incorrecto o con formato incorrecto
Pedido fue cancelado o removido
Pedido pertenece a otro comerciante

Solución:

Verifique si el id del pedido está en formato UUID válido
Confirme que el pedido existe en su sistema
Verifique los registros para confirmar el ID correcto

Error `409 Conflict` al adicionar ítem

Mensaje: Conflict while adding itemCausas:

Producto no existe en el catálogo de la tienda
Pedido ya fue finalizado
Separación aún no fue iniciada

Solución:

Confirme que el código ean del producto es correcto
Verifique si el producto está activo en el catálogo
Asegúrese de que iniciou la separación antes de adicionar ítems
Verifique si la separación aún no ha sido finalizada

Error `409 Conflict` al finalizar la separación

Mensaje: Conflict while finishing separationCausas:

Reglas específicas de método de pago no permiten la edición
Cobro adicional no autorizado para el método de pago
Separación ya fue finalizada
Separación aún no fue iniciada

Solución:

Revise las alteraciones realizadas en los ítems
Verifique si todas las ediciones respetan las reglas de valor del método de pago
Si hay cobro adicional, confirme si es permitido para el método de pago utilizado
Si es necesario, revierta algunas ediciones e intente nuevamente

Error `401 Unauthorized`

Mensaje: UnauthorizedCausas:

Token JWT ausente
Token JWT expirado
Token JWT inválido

Solución:

Verifique si el encabezado Authorization: Bearer TU_TOKEN está presente
Genere un nuevo token si el actual expiró
Valide el token JWT en un decodificador en línea para verificar su estructura

Mejores prácticas para tratamiento de errores

1. Siempre validar antes de ejecutar

# Antes de adicionar un ítem, confirme:
# - El pedido existe
# - La separación fue iniciada
# - El producto existe en el catálogo

2. Implementar reintentos con backoff exponencial

Para errores 500 Internal Server Error, implemente una política de reintentos:

Primer intento: inmediato
Segundo intento: 2 segundos
Tercer intento: 4 segundos
Cuarto intento: 8 segundos

Máximo de 4 intentos.

3. Registrar errores detalladamente

Siempre registre:

Timestamp del error
Código de la solicitud (método + endpoint)
ID del pedido
Código de error retornado
Mensaje de error
Cuerpo de la solicitud (sin datos sensibles)

4. Respetar límites de tasa

Todos los endpoints del módulo Picking tienen un límite de 1000 solicitudes por segundo (req/s). Si recibe error 429 (Too Many Requests):

Espere algunos segundos antes de intentar nuevamente
Implemente backoff exponencial como se recomienda
Revise el comportamiento de su aplicación para identificar loops innecesarios
Considere almacenar respuestas en caché cuando sea apropiado

Consejos de debugging

Verificar token JWT

Decodifique el token en https://jwt.io
Confirme que exp es mayor que el timestamp actual
Verifique si los claims esperados están presentes

Validar formato de UUID

# Formato válido:
550e8400-e29b-41d4-a716-446655440000

# Herramientas en línea:
# https://www.uuidgenerator.net/version4

Probar endpoints con cURL

# Agregue bandera -v para debug detallado
curl -v -X POST https://merchant-api.ifood.com.br/picking/v1.0/orders/{id}/items \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 2, "ean": "1234567890"}'

Monitorear logs

Mantenga un registro detallado de:

Todas las solicitudes y respuestas
Timestamps y duraciones
Errores y excepciones
IDs de transacción para rastreo

Preguntas frecuentes

P: ¿Por cuánto tiempo es válido un token JWT?

R: La validez del token depende de la configuración de su cuenta. Generalmente es de 1 hora. Implemente actualización automática cuando el token esté próximo a expirar.

P: ¿Puedo modificar ítems después de finalizar la separación?

R: No. Después de ejecutar POST /endSeparation, todas las ediciones están bloqueadas. Debe hacer todos los cambios antes de finalizar.

P: ¿Qué hacer si un cliente solicita una alteración después de que la separación sea finalizada?

R: Esto requiere actualizaciones en el sistema de iFood. Contacte con soporte para evaluar opciones de reversión o reembolso.

P: ¿Cómo saber si un producto está disponible antes de intentar adicionarlo?

R: Puede consultar el catálogo de la tienda o intentar adicionar y tratar el error 409 Conflict si el producto no existe.

P: ¿Cuántas solicitudes puedo hacer por segundo?

R: Esto varía por endpoint. Monitoree los encabezados de respuesta para información sobre límite de tasa. Si recibe error de límite de tasa, espere e intente nuevamente.