Error Codes

My Warranties API uses conventional HTTP response codes and provides detailed error information in JSON format.

HTTP Status Codes

Success Codes (2xx)

Code	Name	Description
200	OK	Request succeeded
201	Created	Resource created successfully
204	No Content	Request succeeded, no content to return

Client Error Codes (4xx)

Code	Name	Description
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Authenticated but lacking permissions
404	Not Found	Resource doesn't exist
409	Conflict	Resource conflict (duplicate, etc.)
422	Unprocessable Entity	Validation failed
429	Too Many Requests	Rate limit exceeded

Server Error Codes (5xx)

Code	Name	Description
500	Internal Server Error	Unexpected server error
503	Service Unavailable	Server temporarily unavailable

Error Response Format

All error responses follow this consistent format:

{
  "error": "ErrorType",
  "message": "Human-readable error description",
  "code": "ERROR_CODE",
  "details": {
    // Additional context (optional)
  }
}

Application Error Codes

Authentication Errors (AUTH_*)

AUTH_INVALID_CREDENTIALS

{
  "error": "AuthenticationError",
  "message": "Invalid email or verification code",
  "code": "AUTH_INVALID_CREDENTIALS"
}

HTTP Status: 401 Cause: Wrong verification code or expired code Solution: Request new code or check email

AUTH_TOKEN_EXPIRED

{
  "error": "AuthenticationError",
  "message": "JWT token has expired",
  "code": "AUTH_TOKEN_EXPIRED"
}

HTTP Status: 401 Cause: JWT token older than 1 hour Solution: Re-authenticate to get new token

AUTH_TOKEN_INVALID

{
  "error": "AuthenticationError",
  "message": "Invalid or malformed JWT token",
  "code": "AUTH_TOKEN_INVALID"
}

HTTP Status: 401 Cause: Token signature invalid or corrupted Solution: Re-authenticate

AUTH_MISSING_TOKEN

{
  "error": "AuthenticationError",
  "message": "Authorization header missing",
  "code": "AUTH_MISSING_TOKEN"
}

HTTP Status: 401 Cause: No Authorization header in request Solution: Add Authorization: Bearer <token> header

Authorization Errors (AUTHZ_*)

AUTHZ_INSUFFICIENT_PERMISSIONS

{
  "error": "AuthorizationError",
  "message": "Requires ROLE_ADMIN",
  "code": "AUTHZ_INSUFFICIENT_PERMISSIONS",
  "details": {
    "required_role": "ROLE_ADMIN",
    "user_roles": ["ROLE_USER"]
  }
}

HTTP Status: 403 Cause: User lacks required role Solution: Contact admin for role upgrade

AUTHZ_RESOURCE_ACCESS_DENIED

{
  "error": "AuthorizationError",
  "message": "You don't have access to this resource",
  "code": "AUTHZ_RESOURCE_ACCESS_DENIED"
}

HTTP Status: 403 Cause: Trying to access another user's resource Solution: Only access your own resources

Validation Errors (VALIDATION_*)

VALIDATION_FAILED

{
  "error": "ValidationError",
  "message": "Request validation failed",
  "code": "VALIDATION_FAILED",
  "details": {
    "violations": [
      {
        "field": "email",
        "message": "This value is not a valid email address."
      },
      {
        "field": "warrantyPeriodMonths",
        "message": "This value should be 1 or more."
      }
    ]
  }
}

HTTP Status: 422 Cause: Request data doesn't meet validation rules Solution: Fix invalid fields listed in violations

VALIDATION_MISSING_FIELD

{
  "error": "ValidationError",
  "message": "Required field missing: productId",
  "code": "VALIDATION_MISSING_FIELD",
  "details": {
    "field": "productId"
  }
}

HTTP Status: 400 Cause: Required field not provided Solution: Include required field in request

VALIDATION_INVALID_FORMAT

{
  "error": "ValidationError",
  "message": "Invalid date format for field: purchaseDate",
  "code": "VALIDATION_INVALID_FORMAT",
  "details": {
    "field": "purchaseDate",
    "expected_format": "YYYY-MM-DD",
    "received": "01/15/2024"
  }
}

HTTP Status: 400 Cause: Data in wrong format Solution: Use correct format (e.g., ISO dates)

Resource Errors (RESOURCE_*)

RESOURCE_NOT_FOUND

{
  "error": "ResourceError",
  "message": "Product with ID 999 not found",
  "code": "RESOURCE_NOT_FOUND",
  "details": {
    "resource_type": "Product",
    "resource_id": 999
  }
}

HTTP Status: 404 Cause: Resource doesn't exist Solution: Check ID is correct

RESOURCE_ALREADY_EXISTS

{
  "error": "ResourceError",
  "message": "User with email user@example.com already exists",
  "code": "RESOURCE_ALREADY_EXISTS",
  "details": {
    "resource_type": "User",
    "conflicting_field": "email",
    "value": "user@example.com"
  }
}

HTTP Status: 409 Cause: Duplicate resource (email, etc.) Solution: Use different value or login if already registered

RESOURCE_DELETED

{
  "error": "ResourceError",
  "message": "This resource has been deleted",
  "code": "RESOURCE_DELETED"
}

HTTP Status: 410 Cause: Resource was deleted Solution: Cannot be recovered

Business Logic Errors (BUSINESS_*)

BUSINESS_WARRANTY_EXPIRED

{
  "error": "BusinessLogicError",
  "message": "Cannot create claim: warranty has expired",
  "code": "BUSINESS_WARRANTY_EXPIRED",
  "details": {
    "warranty_end_date": "2023-12-31",
    "current_date": "2024-01-15"
  }
}

HTTP Status: 422 Cause: Business rule violation Solution: Check warranty status before creating claim

BUSINESS_CLAIM_ALREADY_CLOSED

{
  "error": "BusinessLogicError",
  "message": "Cannot modify closed claim",
  "code": "BUSINESS_CLAIM_ALREADY_CLOSED"
}

HTTP Status: 422 Cause: Trying to modify finalized claim Solution: Create new claim instead

BUSINESS_INVALID_STATE_TRANSITION

{
  "error": "BusinessLogicError",
  "message": "Cannot transition claim from 'closed' to 'open'",
  "code": "BUSINESS_INVALID_STATE_TRANSITION",
  "details": {
    "current_state": "closed",
    "requested_state": "open",
    "allowed_transitions": ["closed"]
  }
}

HTTP Status: 422 Cause: Invalid status change Solution: Use valid state transition

Rate Limit Errors (RATE_LIMIT_*)

RATE_LIMIT_EXCEEDED

{
  "error": "RateLimitError",
  "message": "Too many requests. Please try again in 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "retry_after": 45,
    "limit": 100,
    "period": "1 hour"
  }
}

HTTP Status: 429 Headers: Retry-After: 45Cause: Too many requests in time window Solution: Wait and retry after specified seconds

File Upload Errors (FILE_*)

FILE_TOO_LARGE

{
  "error": "FileError",
  "message": "File size exceeds maximum of 10MB",
  "code": "FILE_TOO_LARGE",
  "details": {
    "max_size": "10MB",
    "file_size": "15MB"
  }
}

HTTP Status: 413 Cause: Uploaded file too large Solution: Compress or resize file

FILE_INVALID_TYPE

{
  "error": "FileError",
  "message": "Invalid file type. Allowed: jpg, png, pdf",
  "code": "FILE_INVALID_TYPE",
  "details": {
    "allowed_types": ["jpg", "png", "pdf"],
    "provided_type": "exe"
  }
}

HTTP Status: 415 Cause: File type not allowed Solution: Convert to supported format

External Service Errors (SERVICE_*)

SERVICE_EMAIL_FAILED

{
  "error": "ServiceError",
  "message": "Failed to send email",
  "code": "SERVICE_EMAIL_FAILED",
  "details": {
    "service": "Resend",
    "reason": "Invalid recipient email"
  }
}

HTTP Status: 500 Cause: External email service error Solution: Retry or contact support

SERVICE_UNAVAILABLE

{
  "error": "ServiceError",
  "message": "Claude AI service temporarily unavailable",
  "code": "SERVICE_UNAVAILABLE",
  "details": {
    "service": "Claude AI",
    "retry_after": 60
  }
}

HTTP Status: 503 Cause: External service down Solution: Retry after specified time

Database Errors (DB_*)

DB_CONNECTION_FAILED

{
  "error": "DatabaseError",
  "message": "Database connection failed",
  "code": "DB_CONNECTION_FAILED"
}

HTTP Status: 503 Cause: Cannot connect to database Solution: Retry, contact support if persistent

DB_CONSTRAINT_VIOLATION

{
  "error": "DatabaseError",
  "message": "Foreign key constraint violation",
  "code": "DB_CONSTRAINT_VIOLATION",
  "details": {
    "constraint": "fk_product_user"
  }
}

HTTP Status: 422 Cause: Data integrity violation Solution: Ensure referenced entities exist

Error Handling Best Practices

Client-Side Handling

try {
  const response = await api.post('/api/products', productData);
  return response.data;
} catch (error) {
  if (error.response) {
    // Server responded with error
    const { code, message, details } = error.response.data;

    switch (code) {
      case 'AUTH_TOKEN_EXPIRED':
        // Redirect to login
        window.location.href = '/login';
        break;

      case 'VALIDATION_FAILED':
        // Show field-specific errors
        details.violations.forEach(v => {
          showFieldError(v.field, v.message);
        });
        break;

      case 'RATE_LIMIT_EXCEEDED':
        // Show retry timer
        showRetryMessage(details.retry_after);
        break;

      default:
        showGenericError(message);
    }
  } else {
    // Network error
    showNetworkError();
  }
}

Retry Logic

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fetch(url, options);
    } catch (error) {
      if (error.response?.status === 429) {
        const retryAfter = error.response.data.details.retry_after;
        await sleep(retryAfter * 1000);
        continue;
      }
      if (error.response?.status >= 500 && i < maxRetries - 1) {
        await sleep(Math.pow(2, i) * 1000); // Exponential backoff
        continue;
      }
      throw error;
    }
  }
}

Rate Limit Headers

All responses include rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

When rate limited:

HTTP/1.1 429 Too Many Requests
Retry-After: 45
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995245

Troubleshooting

401 vs 403

• 401 Unauthorized: Authentication missing/invalid → Login required
• 403 Forbidden: Authenticated but lacks permission → Different user/role needed

400 vs 422

• 400 Bad Request: Malformed request (syntax error, missing required field)
• 422 Unprocessable Entity: Valid syntax but business logic validation failed

Logging Errors

All errors are logged server-side with:

• Error code
• Request details
• User information (if authenticated)
• Timestamp
• Stack trace (if applicable)

Related

• Authentication - Auth errors
• Rate Limiting - Rate limit details
• Pagination - Pagination errors