All Safefy API responses follow a consistent format, making it easy to handle success and error cases.
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "Pending",
"amount": 1000
},
"message": "Transaction created successfully"
}
{
"data": null,
"error": {
"code": "VALIDATION_ERROR",
"message": "The 'amount' field must be greater than zero"
}
}
HTTP status codes
| Code | Meaning |
|---|
200 | Success |
201 | Resource created |
400 | Validation error |
401 | Not authenticated |
403 | Not authorized |
404 | Resource not found |
409 | Conflict (e.g., duplicate externalId) |
429 | Rate limit exceeded |
500 | Internal server error |
Error codes
| Code | Description |
|---|
VALIDATION_ERROR | Invalid or missing fields |
AUTHENTICATION_REQUIRED | Token not provided |
INVALID_TOKEN | Invalid or expired token |
FORBIDDEN | Unauthorized IP or insufficient permissions |
NOT_FOUND | Resource not found |
DUPLICATE_EXTERNAL_ID | externalId already exists |
INSUFFICIENT_BALANCE | Insufficient balance for cashout |
RATE_LIMIT_EXCEEDED | Too many requests |
INTERNAL_ERROR | Internal error |
Handling errors
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) {
switch (result.error.code) {
case 'VALIDATION_ERROR':
console.error('Invalid data:', result.error.message);
break;
case 'INVALID_TOKEN':
break;
default:
console.error('Error:', result.error.message);
}
} else {
console.log('Transaction created:', result.data);
}
} catch (error) {
console.error('Network error:', error);
}
Rate limiting
When you exceed the request limit, the API returns 429 with the Retry-After header:
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Request limit exceeded. Try again in 60 seconds."
}
}
Use the Retry-After header to know when you can retry.
