500 Internal Server Error

A 500 Internal Server Error indicates that the server encountered an unexpected condition that prevented it from fulfilling the request. These errors are typically temporary and should be retried with exponential backoff if retries are required.

Error Types

Internal Server Error

Type: https://partner.utopi.io/docs/help/error-codes/500#internal-server-error

Description

An unexpected error occurred on the server while processing the request.

Example

{
  "type": "https://partner.utopi.io/docs/help/error-codes/500#internal-server-error",
  "status": 500,
  "title": "Internal Server Error",
  "detail": "An unexpected error occurred while processing the request.",
  "errors": []
}

Resolution

1. Retry with Exponential Backoff - Wait and retry the request with increasing delays
2. Limit Retry Attempts - Maximum of 3-5 attempts to avoid overloading the server
3. Implement Graceful Error Handling - Show user-friendly messages and provide fallbacks
4. Contact Support - If errors persist, contact your technical contact with error details

Retry Implementation

Example Code

async function apiRequestWithRetry(endpoint, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(endpoint, options);

      if (response.status === 500) {
        if (attempt === maxRetries) {
          throw new Error("Max retries reached");
        }

        // Exponential backoff: 1s, 2s, 4s
        const delay = Math.pow(2, attempt - 1) * 1000;
        await new Promise((resolve) => setTimeout(resolve, delay));
        continue;
      }

      return response;
    } catch (error) {
      if (attempt === maxRetries) {
        throw error;
      }
    }
  }
}

Guidelines

• Maximum Retries - 3-5 attempts
• Backoff Strategy - Exponential (1s, 2s, 4s, 8s)
• Maximum Delay - Cap at 60 seconds
• Add Jitter - Randomise delays to prevent thundering herd

Getting Help

If you continue to experience 500 errors after implementing retry logic:

1. Contact your technical contact or support@utopi.co.uk with:
   • Error frequency and patterns
   • Affected endpoints
   • Full error response
   • Steps to reproduce