Buscar en la documentación

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluciones

Tratamento de erros

Referência completa de códigos de erro e como resolvê-los.

Erros HTTP

Código	Nome	Quando ocorre	Solução
200	OK	Sucesso	Nenhuma - tudo bem
201	Created	Resposta criada com sucesso	Nenhuma - continue
400	Bad Request	Parâmetros inválidos	Validar entrada
401	Unauthorized	JWT expirado ou inválido	Renovar token
403	Forbidden	Sem permissão nesta loja	Verificar ID da loja
404	Not Found	Recurso não existe	Validar IDs (merchant/review)
409	Conflict	Conflito de estado	Já existe resposta/outro conflito
422	Unprocessable Entity	Validação falhou	Verificar dados enviados
500	Internal Server Error	Erro no servidor	Retry com backoff

Erros por endpoint

GET /merchants/{id}/reviews

Listar avaliações.

400 - Bad Request

Causa: pageSize acima do limite ou formato de data inválido.

# Errado: pageSize > 50
GET /merchants/{id}/reviews?pageSize=100
Response: 400 Bad Request

# Correto
GET /merchants/{id}/reviews?pageSize=50

Resposta de erro:

{
  "error": "pageSize must be <= 50",
  "status": 400
}

Solução: Usar pageSize máximo de 50.

Causa: Data em formato inválido.

# Errado
GET /merchants/{id}/reviews?dateFrom=01/04/2025

# Correto (ISO 8601)
GET /merchants/{id}/reviews?dateFrom=2025-04-01T00:00:00Z

Solução: Usar ISO 8601 com fuso horário (Z para UTC).

401 - Unauthorized

Causa: Token expirado ou ausente.

# Token expirado
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Response: 401 Unauthorized

# Renovar via endpoint de autenticação
POST https://merchant-api.ifood.com.br/authentication/v1.0/oauth/token
{
  "grant_type": "refresh_token",
  "refresh_token": "..."
}

Solução:

Extrair refresh_token do login
Chamar endpoint de refresh
Usar novo access_token

403 - Forbidden

Causa: Merchant não existe ou sem permissão.

{
  "error": "Access denied to this merchant",
  "status": 403
}

Solução: Verificar se:

ID da loja está correto
Você tem acesso a esta loja
Seu usuário tem permissão

404 - Not Found

Causa: Merchant não existe.

{
  "error": "Merchant not found",
  "status": 404
}

Solução: Validar ID da loja.

GET /merchants/{id}/reviews/{reviewId}

Obter detalhes de uma avaliação.

401 - Unauthorized

Mesmo que listagem (veja acima).

403 - Forbidden

{
  "error": "This review does not belong to your merchant",
  "status": 403
}

Solução: Verificar se a review pertence à sua loja.

404 - Not Found

Causa: Review não existe.

{
  "error": "Review not found",
  "status": 404
}

Solução:

Verificar ID da review
Confirmar que pertence a você
Usar listagem para encontrar reviews válidas

POST /merchants/{id}/reviews/{reviewId}/answers

Responder uma avaliação.

400 - Bad Request

Causa: Texto muito curto ou muito longo.

# Texto < 10 caracteres
POST /merchants/{id}/reviews/{id}/answers
{
  "text": "Obrigado"  // 7 caracteres
}
Response: 400 Bad Request

# Texto válido (10-300)
{
  "text": "Muito obrigado pelo seu feedback positivo!"  // 44 caracteres
}

Resposta de erro:

{
  "error": "text must be between 10 and 300 characters",
  "status": 400
}

Solução:

Mínimo: 10 caracteres
Máximo: 300 caracteres

401 - Unauthorized

Mesmo que acima (renovar token).

403 - Forbidden

Causa: Sem permissão para responder.

{
  "error": "You don't have permission to reply to this review",
  "status": 403
}

404 - Not Found

Causa: Review não existe.

409 - Conflict

Causa: Review tem status diferente de NOT_REPLIED.

# Exemplos que causam 409:
# - Status: PUBLISHED (já foi publicada)
# - Status: DISCARDED (foi descartada)
# - Status: REPLIED (já tem resposta)

Resposta de erro:

{
  "error": "Review must have status NOT_REPLIED to receive an answer",
  "status": 409
}

Solução:

Verificar status da review: GET /merchants/{id}/reviews/{id}
Só é possível responder status: NOT_REPLIED
Se já respondeu, pode editar por até 10 minutos

422 - Unprocessable Entity

Causa: Validação falhou (conteúdo impróprio, etc).

{
  "error": "Response failed validation: inappropriate content detected",
  "status": 422,
  "details": {
    "reason": "INAPPROPRIATE_CONTENT"
  }
}

Solução:

Revisar conteúdo da resposta
Remover palavras ofensivas ou inadequadas
Ser respeitoso e profissional

Exemplos de conteúdo bloqueado:

Xingamentos ou linguagem agressiva
Informações pessoais do cliente
Links ou promoções não autorizadas
Conteúdo discriminatório

GET /merchants/{id}/summary

Obter resumo.

401 - Unauthorized

Mesmo (renovar token).

403 - Forbidden

Sem acesso à loja.

404 - Not Found

Merchant não existe.

Estratégia de retry

Implementar backoff exponencial para erros transientes:

async function apiCallWithRetry(endpoint, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(endpoint);

      if (response.ok) {
        return response.json();
      }

      // Erros transientes (tentar novamente)
      if (response.status === 500 || response.status === 503) {
        const delay = Math.pow(2, attempt) * 1000; // 2s, 4s, 8s
        console.log(`Retry attempt ${attempt} after ${delay}ms`);
        await sleep(delay);
        continue;
      }

      // Erros permanentes (parar)
      throw new Error(`${response.status}: ${response.statusText}`);

    } catch (error) {
      if (attempt === maxRetries) throw error;
    }
  }
}

Padrão recomendado:

Tentativa 1: Imediato
Tentativa 2: Aguarde 2 segundos
Tentativa 3: Aguarde 4 segundos
Falha: Log e alertar usuário

Autenticação (401)

Cenário: Token expirado

# 1. Requisição com token expirado
curl -X GET "https://merchant-api.ifood.com.br/review/v2.0/merchants/{id}/reviews" \
  -H "Authorization: Bearer eyJ...OLD_TOKEN"
# Response: 401 Unauthorized

# 2. Renovar token usando refresh_token
curl -X POST "https://keycloak.ifood.com.br/realms/merchant/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id={CLIENT_ID}" \
  -d "client_secret={CLIENT_SECRET}" \
  -d "refresh_token={REFRESH_TOKEN}"
# Response: 200 OK
# {
#   "access_token": "eyJ...NEW_TOKEN",
#   "refresh_token": "eyJ...NEW_REFRESH",
#   "expires_in": 300
# }

# 3. Tentar novamente com novo token
curl -X GET "https://merchant-api.ifood.com.br/review/v2.0/merchants/{id}/reviews" \
  -H "Authorization: Bearer eyJ...NEW_TOKEN"
# Response: 200 OK