Error Codes & Messages

Complete reference for API error codes, HTTP status codes, and error messages in Tandem Beam. Use this guide to troubleshoot API integration and tracking issues.

Technical Reference
Error Handling

HTTP Status Codes

Tandem Beam API uses standard HTTP status codes to indicate success or failure:

Success Responses

200 OK

Success

Request processed successfully. Event tracked and queued for platform delivery. 

{
  "success": true,
  "event_id": 1234,
  "message": "Event tracked successfully"
}

201 Created

Platform API

Platform API successfully received and created conversion event. Common for LinkedIn, Meta.

Client Errors (4xx)

400 Bad Request

Client Error

Request contains invalid data or missing required fields.

Common 400 Error Messages:

"Validation failed" / "Validation Error"

Cause: Missing required fields or invalid field formats

Solution: Review request payload against event schema, ensure all required fields present

"PII must be hashed"

Cause: Raw email or phone detected in user_data (unhashed PII)

Solution: Hash email/phone with SHA-256 before sending, use email_hash and phone_hash fields

"laser_beam_session required"

Cause: Session ID missing from request

Solution: Include session ID in event data (ClickBeam handles automatically)

"Unknown test scenario" / "Unknown test type"

Cause: Invalid test parameter in platform testing

Solution: Use valid test scenario names, check platform test documentation

401 Unauthorized

Auth Error

Authentication failed - invalid or missing API token.

Common 401 Error Messages:

"Unauthorized - No token provided"

Cause: Missing Authorization header

Solution: Add Authorization: Bearer your_token header

"Unauthorized - Invalid token"

Cause: Token doesn't exist or has been revoked

Solution: Verify token is active in advertiser dashboard, regenerate if necessary

"Unauthorized - Invalid token, token expired"

Cause: API token expired

Solution: Generate new API token in advertiser dashboard

"Unauthorized - Invalid tenant"

Cause: Token associated with different advertiser

Solution: Verify using correct token for advertiser, check advertiser ID in initialization

403 Forbidden

Access Denied

Authenticated but not authorized for requested resource or feature.

"Access denied" / "Insufficient permissions"

Cause: User role lacks permission for operation

Solution: Contact admin to verify permissions, check user role assignment

"SkyBeam/ClickBeam access required"

Cause: Advertiser doesn't have required feature access

Solution: Enable SkyBeam or ClickBeam access for advertiser

404 Not Found

Not Found

Requested resource doesn't exist.

"Tenant not found"

Cause: Advertiser ID doesn't exist or invalid

Solution: Verify advertiser ID is correct, check advertiser exists in system

"Documentation page not found"

Cause: Requested documentation page doesn't exist

Solution: Check URL path, browse available documentation from docs index

429 Too Many Requests

Rate Limited

Rate limit exceeded - too many requests in short time period.

"Rate Limit Exceeded"

Cause: Too many API requests from same source

Solution: Implement exponential backoff retry logic, reduce request frequency, use batch API if available

Server Errors (5xx)

500 Internal Server Error

Server Error

Unexpected server error occurred during request processing.

What to do:

  • 1. Note the trace ID from response headers
  • 2. Retry request after brief delay (may be transient)
  • 3. If persists, contact support with trace ID and request details

Validation Error Details

400 Bad Request responses include detailed validation error information:

Example validation error response:

{
  "error": "Validation Error",
  "message": "The request contains invalid data",
  "details": {
    "event_data.value": [
      "The value field must be a number"
    ],
    "event_data.currency": [
      "The currency field must be a valid ISO 4217 code"
    ],
    "user_data.em": [
      "Raw email detected - must be SHA-256 hashed"
    ]
  }
}

Tip: The details object contains field-specific validation errors. Fix each field listed and retry.

Platform API Errors

Errors from advertising platform APIs (visible in Queue Management and platform event logs):

Platform Authentication Errors

"Invalid access token"

Platforms: Meta, LinkedIn, TikTok, Pinterest, Reddit

Solution: Refresh platform credentials, verify token permissions (ads_management, conversions), reconnect platform

"Invalid API token or insufficient permissions"

Platforms: Cloudflare, CDN configurations

Solution: Verify API token permissions in platform settings, ensure Worker:Edit permissions for Cloudflare

Platform Configuration Errors

"Conversion config required"

Platforms: Meta, LinkedIn

Solution: Add Pixel ID (Meta) or Conversion Rule URN (LinkedIn) in Event Settings

"Missing required fields"

Cause: Platform API requires fields not included in event data

Solution: Review platform requirements, add required fields to event tracking code

Common Resolution Steps

For 401/403 Errors

  1. 1. Verify API token is active in advertiser dashboard
  2. 2. Check Authorization header format: Bearer token
  3. 3. Ensure token matches advertiser ID being accessed
  4. 4. Generate new token if expired or revoked
  5. 5. Verify user role has required permissions

For 400 Validation Errors

  1. 1. Review details object in error response
  2. 2. Check each field mentioned against event schema
  3. 3. Verify PII fields are hashed (email_hash, phone_hash)
  4. 4. Ensure numeric fields are numbers not strings
  5. 5. Validate currency codes are ISO 4217 format (USD, EUR, etc.)

For Platform API Errors

  1. 1. Use "Test Connection" to identify specific error
  2. 2. Check platform credentials haven't expired
  3. 3. Verify platform API permissions are sufficient
  4. 4. Review Queue Management for failed job details
  5. 5. Reconnect platform if credentials need refresh

For 500 Server Errors

  1. 1. Note trace ID from response headers
  2. 2. Wait 30-60 seconds and retry (may be transient)
  3. 3. Check system status page for known issues
  4. 4. If persistent, contact support with trace ID
  5. 5. Include full request details and error response

Next Steps

For more detailed troubleshooting guidance, consult the troubleshooting guide with step-by-step debugging procedures.

Troubleshooting Guide → API Reference