6. Modelo de Dados — Saída (Erro)

Este capítulo detalha as respostas de erro e como resolvê-los.

---

6.1 Estrutura Geral de Erro

Campos Comuns a Todas as Respostas de Erro

Campo	Tipo	Presença	Descrição
success	Boolean	Sempre	false para erros
message	String	Sempre	Descrição do erro
errors	Array	Operações individuais	Lista de erros específicos

---

6.2 HTTP 400 Bad Request — Validação Falhou

Usado quando: Dados inválidos, campos obrigatórios ausentes, ou violação de regras.

Exemplo 1: Campo Obrigatório Ausente

Requisição:

POST https://api.retailportal.com/erp-data/product HTTP/1.1
Content-Type: application/json
X-API-Key: ERP-RETAILPORTAL-2024-SECURE-KEY-ABC123

{
  "erpId": 12345,
  "ncmCode": "84733090",
  "status": "Active"
  // Faltando: description
}

Resposta (400 Bad Request):

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    "Field 'description' is required"
  ]
}

Como resolver: 1. Adicione o campo obrigatório description 2. Certifique-se de que não está vazio 3. Reenvie a requisição

---

Exemplo 2: Tipo de Dado Incorreto

Requisição:

{
  "erpId": "não é um número",
  "ncmCode": "84733090",
  "status": "Active",
  "description": "Dipirona 500mg"
}

Resposta (400 Bad Request):

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    "Field 'erpId' must be a number"
  ]
}

Como resolver: 1. Converta o valor para o tipo correto (número inteiro) 2. Use "erpId": 12345 em vez de "erpId": "12345" 3. Reenvie

---

Exemplo 3: Tamanho Máximo Excedido

Requisição:

{
  "erpId": 12345,
  "ncmCode": "84733090123456789",
  "status": "Active",
  "description": "Dipirona 500mg"
}

Resposta (400 Bad Request):

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    "Field 'ncmCode' must not exceed 8 characters. Received 17 characters."
  ]
}

Como resolver: 1. Verifique o comprimento máximo na documentação (NCM = 8 caracteres) 2. Truncate o valor para o tamanho máximo 3. Reenvie

---

Exemplo 4: Formato de Data Inválido

Requisição:

{
  "erpProductId": "12345",
  "erpStoreId": "1001",
  "date": "2024-12-06",
  "quantity": 15.00,
  "totalSellValue": 125.50
}

Resposta (400 Bad Request):

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    "Field 'date' must be in UTC ISO 8601 format with Z: YYYY-MM-DDTHH:mm:ssZ"
  ]
}

Como resolver: 1. Use o formato ISO 8601 completo com timezone Z 2. Exemplo correto: "2024-12-06T00:00:00Z" 3. Reenvie

---

Exemplo 5: Batch Vazio

Requisição:

{
  "products": []
}

Resposta (400 Bad Request):

{
  "success": false,
  "message": "The batch of products cannot be empty",
  "totalItems": 0,
  "invalidItems": 0,
  "itemErrors": [
    {
      "index": -1,
      "errors": [
        "Batch list is empty"
      ]
    }
  ]
}

Como resolver: 1. Adicione pelo menos 1 item ao batch 2. Remova a requisição vazia 3. Reenvie com dados válidos

---

Exemplo 6: Batch Oversized (Acima de 1.000 Itens)

Requisição:

{
  "products": [
    // ... 1.001 produtos
  ]
}

Resposta (400 Bad Request):

{
  "success": false,
  "message": "Batch size exceeds maximum allowed (1000 items). Received 1001 items.",
  "totalItems": 1001,
  "invalidItems": 1001,
  "itemErrors": [
    {
      "index": -1,
      "errors": [
        "Batch size exceeds limit"
      ]
    }
  ]
}

Como resolver: 1. Divida o batch em múltiplas requisições 2. Envie máximo 1.000 itens por requisição 3. Reenvie em chunks separados

---

Exemplo 7: Erro de Validação em Item Específico do Batch

Requisição:

{
  "products": [
    {
      "erpId": 12345,
      "ncmCode": "84733090",
      "status": "Active",
      "description": "Dipirona 500mg"
    },
    {
      "erpId": 12346,
      // Faltando: ncmCode
      "status": "Active",
      "description": "Ibuprofeno 600mg"
    }
  ]
}

Resposta (400 Bad Request):

{
  "success": false,
  "message": "Validation failed at item 1",
  "totalItems": 2,
  "invalidItems": 1,
  "itemErrors": [
    {
      "index": 1,
      "errors": [
        "Field 'ncmCode' is required"
      ]
    }
  ]
}

Interpretação: - index: 1 — Erro no segundo item (0-based index) - errors: ["Field 'ncmCode' is required"] — Campo obrigatório ausente

Como resolver: 1. Localize o item no índice 1 (segundo item) 2. Adicione o campo faltante ncmCode 3. Reenvie o batch

---

6.3 HTTP 401 Unauthorized — Autenticação Falhou

Usado quando: API Key ausente, inválida, ou expirada.

Exemplo 1: API Key Ausente

Requisição:

POST https://api.retailportal.com/erp-data/product HTTP/1.1
Content-Type: application/json

{
  "erpId": 12345,
  "ncmCode": "84733090",
  "status": "Active",
  "description": "Dipirona 500mg"
}

Resposta (401 Unauthorized):

HTTP/1.1 401 Unauthorized
Content-Type: application/json

"Unauthorized"

Como resolver: 1. Adicione o cabeçalho X-API-Key 2. Use sua chave de acesso 3. Reenvie

---

Exemplo 2: API Key Inválida

Requisição:

POST https://api.retailportal.com/erp-data/product HTTP/1.1
Content-Type: application/json
X-API-Key: CHAVE-ERRADA-12345

{...}

Resposta (401 Unauthorized):

{
  "message": "Unauthorized: Invalid API Key"
}

Como resolver: 1. Verifique se a chave está correta 2. Verifique se não tem espaços extras 3. Se a chave está correta, ela pode estar expirada 4. Contacte o suporte para nova chave

---

Exemplo 3: Muitas Tentativas Falhadas (Rate Limited)

Requisição (tentativa 101 em 5 minutos):

POST https://api.retailportal.com/erp-data/product HTTP/1.1
X-API-Key: CHAVE-INVALIDA-123

Resposta (429 Too Many Requests):

{
  "message": "Too many authentication attempts. Please try again later",
  "retryAfter": 45,
  "resetTime": "2024-12-06T10:45:30Z"
}

Interpretação: - retryAfter: 45 — Aguarde 45 segundos - resetTime — Bloqueio será removido em 10:45:30 UTC

Como resolver: 1. Aguarde os segundos indicados em retryAfter 2. Revise e corrija a autenticação 3. Use a chave correta na próxima tentativa 4. Evite múltiplas tentativas rápidas

---

6.4 HTTP 404 Not Found — Recurso Não Encontrado

Usado quando: Recurso não existe, ou job expirou.

Exemplo 1: Batch Job Não Encontrado

Requisição:

GET https://api.retailportal.com/erp-data/batch-job-report/job-invalido-123 HTTP/1.1
X-API-Key: ERP-RETAILPORTAL-2024-SECURE-KEY-ABC123

Resposta (404 Not Found):

{
  "message": "Batch job not found",
  "jobId": "job-invalido-123"
}

Como resolver: 1. Verifique se o jobId está correto 2. Certifique-se de que copiou corretamente da resposta 202 Accepted 3. Jobs expiram após 30 dias (consulte status antes disso)

---

Exemplo 2: Produto Não Encontrado para Atualização

Requisição:

PUT https://api.retailportal.com/erp-data/product HTTP/1.1
X-API-Key: ERP-RETAILPORTAL-2024-SECURE-KEY-ABC123
Content-Type: application/json

{
  "erpId": 99999999,
  "description": "Novo nome"
}

Resposta (404 Not Found):

{
  "success": false,
  "message": "Product with ErpId 99999999 not found"
}

Como resolver: 1. Verifique se o erpId existe na plataforma 2. Crie o produto primeiro com POST 3. Depois atualize com PUT

---

6.5 HTTP 409 Conflict — Conflito de Dados

Usado quando: Dados duplicados ou violam regra única.

Exemplo: Produto Duplicado

Requisição (segunda tentativa com mesmo erpId):

{
  "erpId": 12345,
  "ncmCode": "84733090",
  "status": "Active",
  "description": "Dipirona 500mg"
}

Resposta (409 Conflict):

{
  "success": false,
  "message": "A product with ErpId 12345 already exists",
  "errors": [
    "Unique constraint violation: ErpId must be unique"
  ]
}

Como resolver: 1. Se é um produto novo, use um erpId diferente 2. Se é uma atualização, use PUT em vez de POST 3. Evie duplicatas

---

6.6 HTTP 500 Internal Server Error — Erro do Servidor

Usado quando: Erro não esperado no servidor.

Exemplo

Resposta (500 Internal Server Error):

{
  "success": false,
  "message": "An unexpected error occurred",
  "errors": [
    "Database connection failed"
  ]
}

Interpretação: - Não é um erro de dados - É um problema do servidor Portal Retail

Como resolver: 1. Aguarde 5 minutos 2. Tente novamente com a mesma requisição (é idempotente) 3. Se persistir, contacte o suporte com: - Timestamp do erro - Detalhes da requisição - JSON que estava enviando

---

6.7 Tabela Resumida de Códigos HTTP

Código	Significado	Causa	Ação
200	OK	Sucesso (GET/PUT)	Nenhuma — Continue
201	Created	Sucesso (POST)	Nenhuma — Armazene o ID
202	Accepted	Batch enfileirado	Consulte status com jobId
400	Bad Request	Validação falhou	Corrija dados e reenvie
401	Unauthorized	API Key inválida	Verifique autenticação
404	Not Found	Recurso inexistente	Verifique IDs/existência
409	Conflict	Duplicado ou violação	Ajuste dados ou use PUT
429	Too Many Requests	Muitas tentativas	Aguarde segundos em Retry-After
500	Internal Server Error	Erro do servidor	Aguarde 5 min e reenvie

---

6.8 Tratamento Programático de Erros

Python

import requests
import json
import time

def criar_produto(dados):
    headers = {
        'X-API-Key': 'SUA-CHAVE-AQUI',
        'Content-Type': 'application/json'
    }

    response = requests.post(
        'https://api.retailportal.com/erp-data/product',
        json=dados,
        headers=headers
    )

    # Tratamento de sucesso
    if response.status_code == 201:
        result = response.json()
        print(f"Produto criado com ID: {result['id']}")
        return result

    # Tratamento de erro de validação
    elif response.status_code == 400:
        error = response.json()
        print(f"Erro de validação:")
        for e in error.get('errors', []):
            print(f"  - {e}")
        return None

    # Tratamento de erro de autenticação
    elif response.status_code == 401:
        print("Chave de API inválida")
        return None

    # Tratamento de erro do servidor
    elif response.status_code == 500:
        print("Erro do servidor. Tentando novamente...")
        time.sleep(5)
        return criar_produto(dados)  # Retry

    # Erro desconhecido
    else:
        print(f"Erro inesperado: {response.status_code}")
        print(response.text)
        return None

# Uso
dados = {
    "erpId": 12345,
    "ncmCode": "84733090",
    "status": "Active",
    "description": "Dipirona 500mg"
}

criar_produto(dados)

cURL

#!/bin/bash

CHAVE_API="SUA-CHAVE-AQUI"
URL="https://api.retailportal.com/erp-data/product"

JSON_DATA='{
  "erpId": 12345,
  "ncmCode": "84733090",
  "status": "Active",
  "description": "Dipirona 500mg"
}'

# Fazer requisição
response=$(curl -s -w "\n%{http_code}" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CHAVE_API" \
  -d "$JSON_DATA" \
  "$URL")

# Separar corpo e status
http_code=$(echo "$response" | tail -n1)
body=$(echo "$response" | sed '$d')

# Verificar status
case $http_code in
  201)
    echo "Sucesso! Produto criado."
    echo "$body" | jq '.'
    ;;
  400)
    echo "Erro de validação:"
    echo "$body" | jq '.errors[]'
    ;;
  401)
    echo "Erro: Autenticação falhou"
    ;;
  500)
    echo "Erro do servidor. Tentando novamente..."
    sleep 5
    bash "$0"
    ;;
  *)
    echo "Erro desconhecido (HTTP $http_code)"
    echo "$body"
    ;;
esac

---

6.9 Checklist de Tratamento de Erro

• [ ] Verificar código HTTP primeiro
• [ ] Se 400: Listar campos com erro
• [ ] Se 401: Validar chave API
• [ ] Se 404: Verificar IDs
• [ ] Se 429: Aguardar segundos em Retry-After
• [ ] Se 500: Aguardar 5 min e reenviar
• [ ] Registrar erro em log com timestamp
• [ ] Notificar responsável se erro crítico
• [ ] Não reenviar automaticamente sem aguardar

---

Próxima Seção

7. Relatório de Execução do Batch