Error Codes

{
	"success": false,
	"message": "Human-readable error description",
	"error": "Additional error details (optional)"
}

{
	"success": false,
	"message": "Insufficient API requests",
	"usage": {
		"remainingRequests": 0,
		"requiredRequests": 5
	}
}

async function apiCallWithRetry(apiCall, maxRetries = 3) {
	for (let attempt = 0; attempt < maxRetries; attempt++) {
		try {
			return await apiCall();
		} catch (error) {
			const status = error.response?.status;

			// Don't retry client errors (except 429)
			if (status >= 400 && status < 500 && status !== 429) {
				throw error;
			}

			// For 429 or 5xx, wait and retry
			if (attempt < maxRetries - 1) {
				const baseDelay =
					status === 429
						? parseInt(error.response?.headers['retry-after'] || 60) * 1000
						: 1000;

				const delay = baseDelay * Math.pow(2, attempt);
				await new Promise((resolve) => setTimeout(resolve, delay));
			} else {
				throw error;
			}
		}
	}
}

function handleAPIError(error) {
	if (!error.response) {
		// Network error
		console.error('Network error:', error.message);
		return {
			type: 'network',
			message: 'Unable to connect to the API',
			retryable: true,
		};
	}

	const { status, data } = error.response;

	switch (status) {
		case 400:
			return {
				type: 'validation',
				message: data.message || 'Invalid request',
				retryable: false,
			};

		case 401:
			return {
				type: 'authentication',
				message: 'Invalid API key',
				retryable: false,
				action: 'CHECK_API_KEY',
			};

		case 403:
			if (data.message?.includes('API requests')) {
				return {
					type: 'quota',
					message: 'API quota exceeded',
					retryable: false,
					action: 'UPGRADE_PLAN',
				};
			}
			return {
				type: 'permission',
				message: data.message || 'Insufficient permissions',
				retryable: false,
				action: 'UPDATE_PERMISSIONS',
			};

		case 404:
			return {
				type: 'not_found',
				message: data.message || 'Resource not found',
				retryable: false,
			};

		case 429:
			return {
				type: 'rate_limit',
				message: 'Rate limit exceeded',
				retryable: true,
				retryAfter: error.response.headers['retry-after'],
			};

		case 500:
		default:
			return {
				type: 'server',
				message: 'Server error occurred',
				retryable: true,
			};
	}
}

// Usage
try {
	const result = await apiCall();
} catch (error) {
	const errorInfo = handleAPIError(error);

	if (errorInfo.retryable) {
		// Retry logic
	} else {
		// Show user-friendly error message
		console.error(errorInfo.message);
	}
}

const ERROR_MESSAGES = {
	'Invalid or inactive API key':
		'There was an authentication problem. Please contact support.',
	'API key does not have access to this team':
		"You don't have permission to access this resource.",
	'Insufficient API requests':
		'API usage limit reached. Please upgrade your plan.',
	'Rate limit exceeded':
		'Too many requests. Please wait a moment and try again.',
	'Snippet not found':
		"The snippet you're looking for doesn't exist or was deleted.",
	default: 'Something went wrong. Please try again or contact support.',
};

function getUserFriendlyMessage(apiError) {
	return ERROR_MESSAGES[apiError.message] || ERROR_MESSAGES.default;
}

class APILogger {
	logError(error, context) {
		const logEntry = {
			timestamp: new Date().toISOString(),
			status: error.response?.status,
			message: error.response?.data?.message,
			endpoint: context.endpoint,
			method: context.method,
			requestId: error.response?.headers['x-request-id'],
			// Don't log API keys!
			user: context.userId,
		};

		// Send to your logging service
		console.error('API Error:', logEntry);

		// Alert on critical errors
		if (error.response?.status >= 500) {
			this.alertTeam(logEntry);
		}
	}

	alertTeam(logEntry) {
		// Send to Slack, PagerDuty, etc.
	}
}