Error Handling

Error Handling

This guide explains the error codes returned by the Koral API and how to handle them in your applications.

Error Response Format

When an error occurs, the Koral API returns a JSON response with an error object:

{
  "error": {
    "code": "invalid_search_id",
    "message": "The Search id provided is invalid or has expired.",
    "documentation_url": "https://docs.koral.ai/errors#invalid_search_id"
  }
}

Common Error Codes

Authentication Errors

Code	Response code	Description
invalid_search_id	401	The search id is invalid or has expired
missing_earch_id	401	No search id was provided

Request Errors

Code	Response code	Description
invalid_request	400	The request was malformed or missing required parameters
invalid_parameter	400	One or more parameters have an invalid value
unsupported_image_format	400	The image format is not supported
image_too_large	400	The image exceeds the maximum allowed size

Rate Limiting Errors

Code	Response code	Description
rate_limit_exceeded	429	You’ve exceeded your rate limit
quota_exceeded	429	You’ve exceeded your monthly quota

Server Errors

Code	Response code	Description
internal_error	500	An unexpected error occurred on the server
service_unavailable	503	The service is temporarily unavailable

Handling Errors

Here’s an example of how to handle errors when using the Koral API:

async function searchImages(query) {
  try {
    const response = await fetch('https://api.koral.ai/v1/search', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        query: query
      })
    });

    const data = await response.json();

    if (!response.ok) {
      const statusCode = response.status;
      // Handle API error
      const error = data.error;
      console.error(`Error ${error.statusCode}: ${error.message}`);

      // Handle specific error types
      if (error.code === 'rate_limit_exceeded') {
        // Wait and retry later
        return scheduleRetry(query);
      }

      throw new Error(error.message);
    }

    return data;
  } catch (error) {
    // Handle network or parsing errors
    console.error('Request failed:', error);
    throw error;
  }
}

Retry Strategy

For rate limiting errors (429), we recommend implementing an exponential backoff strategy:

function scheduleRetry(query, attempt = 1) {
  const maxAttempts = 5;
  const baseDelay = 1000; // 1 second

  if (attempt > maxAttempts) {
    throw new Error('Maximum retry attempts exceeded');
  }

  const delay = baseDelay * Math.pow(2, attempt - 1);

  return new Promise((resolve) => {
    setTimeout(() => {
      resolve(searchImages(query, attempt + 1));
    }, delay);
  });
}

Next Steps

• Explore the API Endpoints
• See Examples of the API in use