Error Handling

Proper error handling is critical for debugging, monitoring, and providing a good integration experience. This document covers error patterns, codes, and best practices for the External Actions API.

Error Types

• Request errors occur when Adobe sends the execution request to your service.
• Processing errors occur during your service's processing logic.
• Callback errors that occur when sending results back to Adobe.
• Synchronous response errors happen when your /submitAsyncAction endpoint cannot accept the request and returns an HTTP error.

400 Bad Request

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required field: email",
    "details": {
      "field": "objectData.objectContext.leadData.email",
      "expected": "string",
      "received": "null"
    }
  }
}

Causes may be due to:

• Malformed JSON
• Missing required fields
• Invalid data types
• Schema validation failures

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing authentication credentials"
  }
}

Causes may be due to:

• Missing authentication headers
• Invalid API keys
• Expired tokens

403 Forbidden

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to access this resource"
  }
}

Causes may be due to:

• Valid credentials but insufficient permissions
• Service disabled for this customer

429 Rate Limit Exceeded

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "retryAfter": 60
  }
}

Causes may be due to:

• Rate limiting enforcement
• Include Retry-After header

500 Internal Server Error

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

Causes may be due to:

• Unexpected server errors
• Service unavailable
• Database errors

503 Service Unavailable

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service is temporarily unavailable"
  }
}

Causes may be due to:

• Planned maintenance
• Temporary outages
• Circuit breaker triggered

Error Handling

Callback with Activity Error

When processing fails but you can still send a callback, use activityData to indicate the error:

{
  "objectData": [
    {
      "activityData": {
        "success": false,
        "errorCode": "ENRICHMENT_FAILED",
        "reason": "External API returned 503 Service Unavailable"
      },
      "leadData": {
        "id": 12345
      }
    }
  ]
}

Always include:

• activityData.success: false
• A stable errorCode
• A clear reason

Use meaningful, consistent error codes. For example:

Callback Error Handling

Adobe Callback Endpoint Errors

When Adobe's callback endpoint returns an error, you will see:

400 Bad Request

{
  "error": {
    "code": "INVALID_CALLBACK",
    "message": "Invalid token"
  }
}

Possible causes are:

• Invalid or expired correlation ID
• Malformed callback payload
• Schema validation failure

If you see this error:

• Log the error
• Do not retry (client error)
• Alert for manual intervention

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing authentication headers"
  }
}

Possible causes are:

• Missing required headers
• Invalid API key
• Expired bearer token

Next steps are:

• Check authentication configuration
• Refresh tokens if expired
• Do not retry without fixing auth

500 Internal Server Error

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred processing the callback"
  }
}

Possible causes are:

• Adobe service temporarily unavailable
• Unexpected data format
• Internal processing error

To resolve, try:

• Implement retry logic with exponential backoff
• Max 3-5 retries
• Alert if all retries fail

Best Practices

Always Echo Required IDs

Even in error cases, always include required entity IDs:

{
  "activityData": {
    "success": false,
    "errorCode": "ENRICHMENT_FAILED"
  },
  "leadData": {
    "id": 12345  // Always include id
  }
}

Maintain a comprehensive error code reference:

errorCodes:
  ENRICHMENT_FAILED:
    description: Data enrichment operation failed
    httpStatus: 200  # Callback succeeds, processing failed
    retryable: true
  INVALID_DATA:
    description: Input data validation failed
    httpStatus: 400
    retryable: false
  RATE_LIMIT_EXCEEDED:
    description: API rate limit exceeded
    httpStatus: 429
    retryable: true