Error Handling

Overview

The API uses standard HTTP status codes and a consistent error response format across all endpoints. This document describes the error handling patterns, status codes, and response formats.

HTTP Status Codes

Success Codes

Client Error Codes

Server Error Codes

Error Response Format

When an error occurs, the API returns a JSON error response:

{
  "errors": [
    {
      "message": "Description of what went wrong",
      "field": "fieldName"
    }
  ]
}

Error Object Properties

Common Error Scenarios

Authentication Errors (401)

Returned when the Bearer token is missing or invalid:

• Token not provided in the Authorization header
• Token has expired
• Token is malformed or invalid

Validation Errors (400)

Returned when request parameters fail validation:

• Required field is null or empty
• Value is out of acceptable range
• Invalid GUID format
• Missing request body

Authorization Errors (403)

Returned when the authenticated user lacks required permissions:

• Non-admin user calling admin-only endpoints (e.g., email dispatcher, migrate assets)
• User without proper role accessing restricted resources

Not Found Errors (404)

Returned when the requested resource does not exist:

• Asset, schedule, collection, tag, or other entity not found by ID
• Share has expired or been deleted
• License does not exist for the specified customer

Webhook Error Handling

Webhook endpoints (S3, Twelve Labs, Mobius Labs, Stripe, etc.) have special error handling:

• S3 Webhook: Returns 200 OK even on processing errors to acknowledge receipt. Returns 400 if the event is invalid.
• Twelve Labs Webhook: Always returns 200 OK to prevent retry storms. Errors are logged but not returned.
• Mobius Labs Webhook: Returns an empty response model and logs errors for unknown callback types.
• Stripe Webhook: Returns the processing result. Errors are propagated.

Batch Operation Errors

Batch operations (collections, tags, related content) return a BatchResultModel that may contain partial success results:

{
  "totalCount": 10,
  "successCount": 8,
  "errorCount": 2,
  "errors": [
    {
      "message": "Item not found",
      "field": "itemId"
    }
  ]
}

Parameter Validation

The API uses consistent validation helpers:

• ThrowIfNull() — Returns 400 if the value is null
• ThrowIfNullOrEmpty() — Returns 400 if the string/GUID is null or empty
• ThrowNotFoundIfNull() — Returns 404 if the value is null

Best Practices

1. Always check the HTTP status code before processing the response body.
2. Handle 401 responses by refreshing the authentication token and retrying.
3. Parse error messages from the response body for user-friendly error display.
4. For batch operations, check both the overall status code and the BatchResultModel for partial failures.
5. For webhook integrations, ensure your endpoint acknowledges receipt quickly to avoid timeout retries.