Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.safefypay.com.br/llms.txt

Use this file to discover all available pages before exploring further.

The Safefy API uses conventional HTTP response codes to indicate the success or failure of requests.

​
Response format

Success: 
{
  "data": { ... },
  "message": "Operation completed successfully."
}
Error: 
{
  "data": null,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance to complete this cashout."
  }
}

​
HTTP status codes

CodeMeaning
200Success
201Resource created
400Validation error or business rule violation
401Not authenticated missing or invalid token
403Unauthorized valid token but insufficient permissions
404Resource not found
409Conflict duplicate externalId
429Rate limit exceeded
500Internal server error

​
Error codes

CodeHTTPDescription
VALIDATION_ERROR400One or more request fields are invalid
AUTHENTICATION_REQUIRED401No authentication token provided
INVALID_TOKEN401Token is invalid or expired
FORBIDDEN403Insufficient permissions for this action
NOT_FOUND404Requested resource does not exist
DUPLICATE_EXTERNAL_ID409The externalId is already in use
INSUFFICIENT_BALANCE400Not enough balance available for the cashout
RATE_LIMIT_EXCEEDED429Too many requests slow down and retry
INTERNAL_ERROR500Unexpected server error

​
Handling errors

try {
  const response = await fetch('https://api-payment.safefypay.com.br/v1/cashouts', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ amount: 5000, pixKeyType: 'CPF', pixKey: '12345678901' }),
  });

  const data = await response.json();

  if (!response.ok) {
    switch (data.error?.code) {
      case 'INSUFFICIENT_BALANCE':
        console.error('Insufficient balance for this cashout.');
        break;
      case 'RATE_LIMIT_EXCEEDED':
        console.error('Rate limit hit. Try again later.');
        break;
      case 'VALIDATION_ERROR':
        console.error('Invalid request:', data.error.message);
        break;
      default:
        console.error('API error:', data.error?.message);
    }
    return;
  }

  console.log('Cashout created:', data.data);
} catch (err) {
  console.error('Network error:', err);
}

​
Rate limiting

When you exceed the allowed request rate, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying.
Always read the Retry-After header and wait the specified duration before retrying. Ignoring this header and retrying immediately will continue to return 429.