API Error Codes

This document describes the standardized error response format and error codes used by the Nuclom API.

Error Response Format

All API errors follow a consistent JSON structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      // Optional additional context
    }
  }
}

Error Code Categories

Error codes follow the format CATEGORY_SPECIFIC_ERROR:

Authentication Errors (401, 403)

Example Response

{
  "error": {
    "code": "AUTH_UNAUTHORIZED",
    "message": "Authentication required"
  }
}

Validation Errors (400)

Example Response

{
  "error": {
    "code": "VALIDATION_MISSING_FIELD",
    "message": "Title is required",
    "details": {
      "field": "title"
    }
  }
}

Not Found Errors (404)

Example Response

{
  "error": {
    "code": "NOT_FOUND_VIDEO",
    "message": "Video not found",
    "details": {
      "entity": "video",
      "id": "video_123"
    }
  }
}

Conflict Errors (409)

Example Response

{
  "error": {
    "code": "CONFLICT_DUPLICATE",
    "message": "A video with this title already exists",
    "details": {
      "entity": "video",
      "field": "title"
    }
  }
}

Storage Errors (500, 503)

Video Processing Errors (400, 500)

Example Response

{
  "error": {
    "code": "VIDEO_FILE_TOO_LARGE",
    "message": "File size exceeds the maximum limit of 500MB",
    "details": {
      "fileSize": 536870912,
      "maxSize": 524288000
    }
  }
}

Billing Errors (400, 402, 403)

Example Response

{
  "error": {
    "code": "BILLING_PLAN_LIMIT_EXCEEDED",
    "message": "You have reached your storage limit",
    "details": {
      "resource": "storage",
      "currentUsage": 10737418240,
      "limit": 10737418240
    }
  }
}

Database Errors (500)

Internal Errors (500)

Client-Side Error Handling

When handling errors in the client, use the error code to provide appropriate user feedback:

import { type ApiErrorResponse, getErrorMessage, ErrorCodes } from "@/lib/api-errors";

async function handleApiResponse(response: Response) {
  if (!response.ok) {
    const data: ApiErrorResponse = await response.json();
    const code = data.error.code;

    // Handle specific errors
    switch (code) {
      case ErrorCodes.AUTH_UNAUTHORIZED:
        // Redirect to login
        window.location.href = "/login";
        break;
      case ErrorCodes.BILLING_PLAN_LIMIT_EXCEEDED:
        // Show upgrade modal
        showUpgradeModal(data.error.details);
        break;
      default:
        // Show generic error message
        toast.error(getErrorMessage(code));
    }
  }
}

HTTP Status Code Summary