Error Codes

This page documents all error codes returned by the LMIF API.

Error Response Format

All errors follow this format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": { ... }
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Authentication Errors

UNAUTHORIZED

HTTP Status: 401

Invalid or missing API key.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key",
    "details": "The provided API key is invalid or has been revoked"
  }
}

Resolution: Check your API key and ensure it hasn’t been revoked.

KEY_REVOKED

HTTP Status: 401

The API key has been explicitly revoked.

{
  "error": {
    "code": "KEY_REVOKED",
    "message": "API key has been revoked",
    "details": "This key was revoked on 2024-01-15T10:00:00Z"
  }
}

Resolution: Generate a new API key from the dashboard.

KEY_EXPIRED

HTTP Status: 401

The API key has expired (typically after rotation).

{
  "error": {
    "code": "KEY_EXPIRED",
    "message": "API key has expired",
    "details": "This key expired after rotation. Use the new key."
  }
}

Resolution: Use the new key provided during rotation.

WRONG_ENVIRONMENT

HTTP Status: 401

Using a sandbox key in production or vice versa.

{
  "error": {
    "code": "WRONG_ENVIRONMENT",
    "message": "API key environment mismatch",
    "details": "Using sandbox key (lmif_test_*) with production endpoint"
  }
}

Resolution: Use the correct key for the environment.

Authorization Errors

FORBIDDEN

HTTP Status: 403

You don’t have permission to access this resource.

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Access denied",
    "details": "You don't have permission to access this box"
  }
}

Resolution: Ensure you have the correct permissions.

INSUFFICIENT_TIER

HTTP Status: 403

Your plan doesn’t include this feature.

{
  "error": {
    "code": "INSUFFICIENT_TIER",
    "message": "Feature not available on your plan",
    "details": {
      "feature": "batch_check",
      "requiredTier": "Standard",
      "currentTier": "Basic"
    }
  }
}

Resolution: Upgrade your plan to access this feature.

Validation Errors

VALIDATION_ERROR

HTTP Status: 400

Request validation failed.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request",
    "details": [
      {
        "field": "name",
        "message": "Name is required"
      },
      {
        "field": "imageUrl",
        "message": "Must be a valid URL"
      }
    ]
  }
}

Resolution: Fix the validation errors indicated in details.

INVALID_IMAGE_URL

HTTP Status: 400

The image URL is invalid or inaccessible.

{
  "error": {
    "code": "INVALID_IMAGE_URL",
    "message": "Could not access image",
    "details": {
      "url": "https://example.com/image.jpg",
      "reason": "404 Not Found"
    }
  }
}

Resolution: Ensure the image URL is publicly accessible.

IMAGE_TOO_LARGE

HTTP Status: 400

The image exceeds the size limit.

{
  "error": {
    "code": "IMAGE_TOO_LARGE",
    "message": "Image exceeds maximum size",
    "details": {
      "size": 15728640,
      "maxSize": 10485760,
      "unit": "bytes"
    }
  }
}

Resolution: Use an image under 10MB.

BATCH_TOO_LARGE

HTTP Status: 400

Batch request exceeds the limit.

{
  "error": {
    "code": "BATCH_TOO_LARGE",
    "message": "Batch size exceeds limit",
    "details": {
      "count": 150,
      "maxCount": 100
    }
  }
}

Resolution: Split into batches of 100 or fewer.

Resource Errors

NOT_FOUND

HTTP Status: 404

The requested resource doesn’t exist.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "details": {
      "resource": "box",
      "id": "box_nonexistent"
    }
  }
}

Resolution: Verify the resource ID is correct.

CLAIM_NOT_VERIFIED

HTTP Status: 400

Attempting to create a box for an unverified claim.

{
  "error": {
    "code": "CLAIM_NOT_VERIFIED",
    "message": "Claim must be verified before boxing",
    "details": {
      "claimId": "claim_xyz789",
      "status": "pending"
    }
  }
}

Resolution: Complete claim verification first.

ALREADY_EXISTS

HTTP Status: 409

Resource already exists.

{
  "error": {
    "code": "ALREADY_EXISTS",
    "message": "Box already exists for this claim",
    "details": {
      "claimId": "claim_xyz789",
      "existingBoxId": "box_abc123"
    }
  }
}

Resolution: Use the existing resource or delete it first.

Rate Limiting

RATE_LIMITED

HTTP Status: 429

Too many requests.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "details": {
      "limit": 300,
      "remaining": 0,
      "resetAt": "2024-01-15T10:01:00Z",
      "retryAfter": 45
    }
  }
}

Resolution: Wait for retryAfter seconds before retrying.

Server Errors

INTERNAL_ERROR

HTTP Status: 500

An unexpected error occurred.

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred",
    "details": {
      "requestId": "req_abc123"
    }
  }
}

Resolution: Retry the request. If it persists, contact support with the requestId.

SERVICE_UNAVAILABLE

HTTP Status: 503

The service is temporarily unavailable.

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable",
    "details": {
      "retryAfter": 30
    }
  }
}

Resolution: Wait and retry. Check status.lookmaimfamous.com for updates.

TIMEOUT

HTTP Status: 504

Request timed out.

{
  "error": {
    "code": "TIMEOUT",
    "message": "Request timed out",
    "details": {
      "timeout": 30000,
      "operation": "image_analysis"
    }
  }
}

Resolution: Try again. For large images, consider compressing.

Webhook Errors

INVALID_WEBHOOK_SIGNATURE

HTTP Status: 401

Webhook signature verification failed.

{
  "error": {
    "code": "INVALID_WEBHOOK_SIGNATURE",
    "message": "Webhook signature verification failed"
  }
}

Resolution: Ensure you’re using the correct webhook secret.

WEBHOOK_ENDPOINT_ERROR

HTTP Status: 400

Error with webhook endpoint.

{
  "error": {
    "code": "WEBHOOK_ENDPOINT_ERROR",
    "message": "Could not reach webhook endpoint",
    "details": {
      "url": "https://yoursite.com/webhooks/lmif",
      "reason": "Connection refused"
    }
  }
}

Resolution: Ensure your endpoint is accessible.

Handling Errors

import { LMIFClient, LMIFError } from '@lookmaimfamous/lmif';

try {
  const result = await lmif.identity.check({ name, imageUrl });
} catch (error) {
  if (error instanceof LMIFError) {
    switch (error.code) {
      case 'UNAUTHORIZED':
        // Re-authenticate or check API key
        break;
      case 'RATE_LIMITED':
        // Wait and retry
        await sleep(error.details.retryAfter * 1000);
        break;
      case 'VALIDATION_ERROR':
        // Fix validation errors
        console.error('Validation errors:', error.details);
        break;
      case 'INTERNAL_ERROR':
        // Retry or alert
        console.error('LMIF error:', error.details.requestId);
        break;
      default:
        throw error;
    }
  }
}