Erros e Regras Gerais

Como esta API é construída sobre o framework PHP Laravel, ela segue padrões rigorosos de resposta para garantir previsibilidade e facilidade de depuração.

---

🚦 Regras Gerais de Integração

Para garantir que suas requisições sejam processadas corretamente, observe as seguintes diretrizes:

1. Header Accept: Sempre envie o header Accept: application/json. Isso garante que o servidor retorne erros no formato JSON em vez de redirecionar para páginas HTML.
2. Codificação: Todas as requisições devem usar a codificação UTF-8.
3. Formato de Data: Utilize o padrão ISO 8601 (YYYY-MM-DD) para campos de data.
4. Prefixos de Token: O token de autorização deve sempre ser precedido pela palavra Bearer.
5. Sanitização: Campos de documento (CPF/CNPJ) e telefone devem conter apenas números, sem formatação (pontos, traços ou parênteses).

---

❌ Tratamento de Erros

A API utiliza códigos de status HTTP para indicar o resultado da operação. Abaixo estão os cenários mais comuns:

422 Unprocessable Entity (Erro de Validação)

Este é o erro mais comum no Laravel. Ele ocorre quando os dados enviados não passam nas regras de negócio (ex: CPF inválido, campo obrigatório ausente).

Exemplo de Resposta:

{
    "message": "The given data was invalid.",
    "errors": {
        "document": [
            "O campo documento deve ter 11 caracteres para CPF."
        ],
        "email": [
            "O email informado já está em uso ou é inválido."
        ],
        "installments": [
            "O número de parcelas é obrigatório para este método de pagamento."
        ]
    }
}

401 Unauthorized

Ocorre quando o token é inválido, expirou ou não foi enviado.

{
    "message": "Unauthenticated."
}

405 Method Not Allowed

Ocorre quando você tenta usar um método HTTP diferente do esperado (ex: usar GET em um endpoint que aceita apenas POST).

{
    "message": "The GET method is not supported for this route. Supported methods: POST."
}

429 Too Many Requests

Implementamos limites de taxa para proteger a infraestrutura. Caso você exceda o número de requisições permitidas por minuto, receberá este erro.

500 Internal Server Error

Indica uma falha inesperada no processador da API. Se este erro persistir, entre em contato com o suporte técnico informando o timestamp da ocorrência.

---

💡 Dica de Depuração

Sempre verifique se o seu cliente HTTP está configurado para tratar respostas que não sejam da família 2xx. No ecossistema Laravel, o corpo do erro (JSON) fornecerá a chave exata para corrigir a implementação.