Errors - Safefy Pay

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

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

Error codes

Code	HTTP	Description
`VALIDATION_ERROR`	400	One or more request fields are invalid
`AUTHENTICATION_REQUIRED`	401	No authentication token provided
`INVALID_TOKEN`	401	Token is invalid or expired
`FORBIDDEN`	403	Insufficient permissions for this action
`NOT_FOUND`	404	Requested resource does not exist
`DUPLICATE_EXTERNAL_ID`	409	The `externalId` is already in use
`INSUFFICIENT_BALANCE`	400	Not enough balance available for the cashout
`RATE_LIMIT_EXCEEDED`	429	Too many requests slow down and retry
`INTERNAL_ERROR`	500	Unexpected 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.