Todas as respostas da API Safefy seguem um formato consistente, facilitando o tratamento de sucesso e erro.
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "Pending",
"amount": 1000
},
"message": "Transação criada com sucesso"
}
{
"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.
