Errors

The 7en Platform API uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range indicate client-side errors (e.g., missing parameters or invalid requests), and codes in the 5xx range indicate server-side errors (these are rare).

Some 4xx errors include specific error codes that can be handled programmatically, providing details about the issue encountered.

Error Codes

Error Object

Error Handling

async function makeApiRequest(endpoint, options) {
  try {
    const response = await fetch(endpoint, options);
    if (!response.ok) {
      const errorData = await response.json();
      if (errorData.error) {
        const { code, message, fields } = errorData.error;

        // Handle field-specific errors for user_validation_error
        if (code === 'user_validation_error' && fields) {
          const fieldErrors = Object.entries(fields)
            .map(([field, errors]) => {
              // Map field names to user-friendly labels
              const fieldLabel = field === 'email' ? 'Email' : field === 'name' ? 'Name' : field;
              return `${fieldLabel}: ${errors.join(', ')}`;
            })
            .join('; ');
          console.error('Validation errors:', fieldErrors);
          alert(`Please fix the following errors: ${fieldErrors}`);
          throw new Error(`Validation failed: ${fieldErrors}`);
        }
        throw new Error(message);
      }
    }
    return response.json();
  } catch (error) {
    console.error('Error:', error.message);
    alert('An error occurred. Please try again.');
    throw error;
  }
}

// Usage example
makeApiRequest('https://api.example.com/v3/agents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ name: '', email: 'invalid' })
}).then(data => console.log('Success:', data))
  .catch(error => console.error('Request failed:', error));

Best Practices

• Check Error Codes: Always inspect the code field in the error response to handle specific errors programmatically. For example, handle authentication_required by prompting the user to re-authenticate or verify the API key.
• Handle Field-Specific Errors: Use the fields object to identify and display specific validation errors to users, such as duplicate emails or invalid inputs, to improve user experience.
• Rate Limit Awareness: Monitor for throttle_exceeded errors and implement exponential backoff or retry logic to respect rate limits (e.g., 100 requests/min for free tier, 1000 for pro, 10000 for enterprise).
• Graceful Degradation: For 5xx server errors, implement fallback mechanisms or retry logic with a reasonable delay to handle temporary server issues.
• Logging and Monitoring: Log errors with their code, message, and status for debugging and monitoring. This helps identify recurring issues like object_not_found or insufficient_permissions.
• User Feedback: Translate error messages into user-friendly notifications. For instance, convert user_validation_error into a clear message like "This email is already in use" for better usability.
• Secure API Key Management: For malformed_api_key or inactive_api_key errors, ensure API keys are securely stored and refreshed as needed via the dashboard settings at https://app.7en.ai/settings.
• Test Error Scenarios: Simulate common errors like agent_validation_error or team_required during development to ensure your application handles them robustly.