Error Handling

Learn how to handle errors when working with the SoshiaConnect API.

Error Response Format

All API errors follow a consistent JSON format:

{
  "success": false,
  "message": "Error description",
  "errors": {
    "field_name": ["Error message for this field"]
  }
}

HTTP Status Codes

The API uses standard HTTP status codes to indicate success or failure:

Status Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or missing authentication
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
422	Validation Error	Input validation failed
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error occurred

Common Error Scenarios

400 Bad Request

Occurs when the request is malformed or contains invalid parameters.

Example:

{
  "success": false,
  "message": "Bad request - Invalid input parameters"
}

How to fix:

• Check that all required parameters are included
• Verify parameter types match the API specification
• Ensure proper data formatting (dates, emails, etc.)

401 Unauthorized

Occurs when authentication credentials are missing or invalid.

Example:

{
  "success": false,
  "message": "Invalid or missing authentication"
}

How to fix:

• Verify your Bearer token or API key is correct
• Check that the token hasn't expired
• Ensure you're using the correct authentication method for the endpoint
• Use /auth/refresh to get a new token if expired

403 Forbidden

Occurs when you're authenticated but don't have permission to access the resource.

Example:

{
  "success": false,
  "message": "Insufficient permissions"
}

How to fix:

• Verify your account has the necessary subscription/plan
• Check that you have access to the requested route or resource
• Ensure your API key is active and not suspended

404 Not Found

Occurs when the requested resource doesn't exist.

Example:

{
  "success": false,
  "message": "Not found - Resource does not exist"
}

How to fix:

• Verify the endpoint URL is correct
• Check that the resource ID exists
• Ensure you're using the correct base URL

422 Validation Error

Occurs when input validation fails.

Example:

{
  "success": false,
  "message": "Validation error - Input validation failed",
  "errors": {
    "email": ["The email field must be a valid email address"],
    "password": ["The password must be at least 8 characters"]
  }
}

How to fix:

• Review the errors object for specific field errors
• Correct the invalid fields and retry
• Check API documentation for field requirements

429 Too Many Requests

Occurs when you exceed the API rate limit.

Example:

{
  "success": false,
  "message": "Too many requests - Rate limit exceeded"
}

How to fix:

• Implement exponential backoff in your requests
• Check the Retry-After header for wait time
• Consider upgrading your plan for higher limits
• Cache responses when possible

500 Internal Server Error

Occurs when the server encounters an unexpected error.

Example:

{
  "success": false,
  "message": "An error occurred"
}

How to fix:

• Retry the request after a short delay
• If the error persists, contact support
• Check the status page for any known issues

Error Handling Best Practices

1. Always Check Status Codes

try {
  const response = await fetch(url, options);

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message);
  }

  const data = await response.json();
  return data;
} catch (error) {
  console.error('API Error:', error);
}

2. Implement Retry Logic

async function apiRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);

      if (response.ok) {
        return await response.json();
      }

      if (response.status === 429) {
        // Rate limited - wait and retry
        const retryAfter = response.headers.get('Retry-After') || 60;
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }

      if (response.status >= 500) {
        // Server error - retry with exponential backoff
        await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
        continue;
      }

      // Client error - don't retry
      throw new Error(await response.text());
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

3. Log Errors for Debugging

function logAPIError(error, context) {
  console.error('API Error:', {
    message: error.message,
    status: error.status,
    context: context,
    timestamp: new Date().toISOString()
  });
}

4. Provide User-Friendly Messages

function getUserFriendlyError(error) {
  const errorMessages = {
    400: 'Invalid request. Please check your input.',
    401: 'Please log in to continue.',
    403: 'You don\'t have permission to perform this action.',
    404: 'The requested resource was not found.',
    422: 'Please correct the highlighted fields.',
    429: 'Too many requests. Please try again later.',
    500: 'Server error. Please try again later.'
  };

  return errorMessages[error.status] || 'An unexpected error occurred.';
}

Debugging Tips

1. Check the Response Body: Always read the full error response for detailed information
2. Verify Headers: Ensure authentication headers are properly formatted
3. Test with curl: Use curl to isolate issues from your application code
4. Enable Logging: Log all API requests and responses during development
5. Check API Status: Visit our status page for any ongoing issues
6. Review Rate Limits: Monitor your API usage to avoid rate limit errors

Getting Help

If you encounter persistent errors:

1. Check the API Reference for endpoint-specific requirements
2. Review our Quick Start Guide for examples
3. Contact support at support@soshiaconnect.com with:
   • Error message and status code
   • Request details (endpoint, parameters)
   • Timestamp of the error
   • Your account information

Rate Limits

To avoid rate limit errors, be aware of these limits:

• Authenticated requests: 1000 requests per hour
• Unauthenticated requests: 60 requests per hour
• Burst limit: 20 requests per second

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1609459200