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": "Transacao criada com sucesso"
}
{
"data": null,
"error": {
"code": "VALIDATION_ERROR",
"message": "O campo 'amount' deve ser maior que zero"
}
}
Codigos HTTP
| Codigo | Significado |
|---|
200 | Sucesso |
201 | Recurso criado |
400 | Erro de validacao |
401 | Nao autenticado |
403 | Nao autorizado |
404 | Recurso nao encontrado |
409 | Conflito (ex: externalId duplicado) |
429 | Rate limit excedido |
500 | Erro interno do servidor |
Codigos de erro
| Codigo | Descricao |
|---|
VALIDATION_ERROR | Campos invalidos ou ausentes |
AUTHENTICATION_REQUIRED | Token nao fornecido |
INVALID_TOKEN | Token invalido ou expirado |
FORBIDDEN | IP nao autorizado ou sem permissao |
NOT_FOUND | Recurso nao encontrado |
DUPLICATE_EXTERNAL_ID | externalId ja existe |
INSUFFICIENT_BALANCE | Saldo insuficiente para saque |
RATE_LIMIT_EXCEEDED | Muitas requisicoes |
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 invalidos:', 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('Transacao criada:', result.data);
}
} catch (error) {
console.error('Erro de rede:', error);
}
Rate limiting
Quando voce excede o limite de requisicoes, 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 requisicoes excedido. Tente novamente em 60 segundos."
}
}
Use o header Retry-After para saber quando pode tentar novamente.
