Erros e respostas - Safefy Pay

Todas as respostas da API Safefy seguem um formato consistente, facilitando o tratamento de sucesso e erro.

Formato de sucesso

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "Pending",
    "amount": 1000
  },
  "message": "Transação criada com sucesso"
}

Formato de erro

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "O campo 'amount' deve ser maior que zero"
  }
}

Códigos HTTP

Código	Significado
`200`	Sucesso
`201`	Recurso criado
`400`	Erro de validação
`401`	Não autenticado
`403`	Não autorizado
`404`	Recurso não encontrado
`409`	Conflito (ex: externalId duplicado)
`429`	Rate limit excedido
`500`	Erro interno do servidor

Códigos de erro

Código	Descrição
`VALIDATION_ERROR`	Campos inválidos ou ausentes
`AUTHENTICATION_REQUIRED`	Token não fornecido
`INVALID_TOKEN`	Token inválido ou expirado
`FORBIDDEN`	IP não autorizado ou sem permissão
`NOT_FOUND`	Recurso não encontrado
`DUPLICATE_EXTERNAL_ID`	externalId já existe
`INSUFFICIENT_BALANCE`	Saldo insuficiente para saque
`RATE_LIMIT_EXCEEDED`	Muitas requisições
`INTERNAL_ERROR`	Erro interno

Tratando erros

try {
  const response = await fetch('https://api-payment.safefypay.com.br/v1/transactions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
  });
  
  const result = await response.json();
  
  if (result.error) {
    // Trata o erro baseado no codigo
    switch (result.error.code) {
      case 'VALIDATION_ERROR':
        console.error('Dados inválidos:', result.error.message);
        break;
      case 'INVALID_TOKEN':
        // Renova o token e tenta novamente
        break;
      default:
        console.error('Erro:', result.error.message);
    }
  } else {
    // Sucesso
    console.log('Transação criada:', result.data);
  }
} catch (error) {
  console.error('Erro de rede:', error);
}

Rate limiting

Quando você excede o limite de requisições, a API retorna 429 com o header Retry-After:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Limite de requisições excedido. Tente novamente em 60 segundos."
  }
}

Use o header Retry-After para saber quando pode tentar novamente.