Response Codes & Error Handling

Response Format

All API responses follow a consistent format with a success flag and relevant data or error information.

Success Response

{
  "success": true,
  "data": {
    // Response data specific to the endpoint
  }
}

Error Response

{
  "success": false,
  "message": "Error description",
  "statusCode": 400
}

HTTP Status Codes

Our API uses standard HTTP status codes to indicate the success or failure of requests.

Success Codes

Status Code	Description	Example Scenario
200	OK	Successfully retrieved recipe
201	Created	Successfully created new recipe

Client Error Codes

Status Code	Description	Example Scenario
400	Bad Request	Invalid input parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	Valid API key but insufficient permissions
404	Not Found	Recipe or job not found
429	Too Many Requests	Rate limit exceeded

Server Error Codes

Status Code	Description	Example Scenario
500	Internal Server Error	Unexpected server error
503	Service Unavailable	Server maintenance

Common Error Types

Authentication Errors

{
  "success": false,
  "message": "Invalid API key",
  "statusCode": 401
}

Common authentication errors:

• "Invalid API key"
• "API key is required"
• "API key has expired"

Rate Limiting

{
  "success": false,
  "message": "Rate limit exceeded. Please try again later",
  "statusCode": 429,
  "retryAfter": 60
}

Rate limiting responses include:

• Current rate limit status
• Time until limit resets
• Recommended retry delay

Resource Errors

{
  "success": false,
  "message": "Recipe not found: rec_123",
  "statusCode": 404
}

Common resource errors:

• "Recipe not found"
• "Job not found"
• "Invalid recipe configuration"

Validation Errors

{
  "success": false,
  "message": "Invalid input parameters",
  "statusCode": 400,
  "errors": [
    {
      "field": "url",
      "message": "Invalid URL format"
    }
  ]
}

Common validation errors:

• "Invalid input parameters"
• "Required field missing"
• "Value out of allowed range"

Error Handling Best Practices

1. Check Success Flag

Always check the success field first:

if (!response.success) {
  handleError(response);
  return;
}

2. Handle Rate Limits

Implement exponential backoff:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      const data = await response.json();
      
      if (response.status === 429) {
        const delay = Math.pow(2, i) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      
      return data;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

3. Validate Input

Validate parameters before making API calls:

function validateRecipe(recipe) {
  if (!recipe.url) {
    throw new Error("URL is required");
  }
  
  if (!recipe.listSelector) {
    throw new Error("List selector is required");
  }
  
  // Additional validation...
}

4. Complete Error Handler

Example of a comprehensive error handler:

function handleApiError(error) {
  switch (error.statusCode) {
    case 401:
      console.error('Authentication failed:', error.message);
      // Refresh token or redirect to login
      break;
      
    case 429:
      console.error('Rate limit exceeded:', error.message);
      // Implement retry logic with backoff
      break;
      
    case 404:
      console.error('Resource not found:', error.message);
      // Show user-friendly error message
      break;
      
    default:
      console.error('API error:', error.message);
      // Generic error handling
  }
}