Amplitude Error Handlers

The Amplitude plugin includes built-in error handlers for common Amplitude API error scenarios.

Built-in Error Handlers

Rate Limit Errors

Triggers: HTTP 429 status

Behavior:

• Maximum retries: 5
• Respects Retry-After header

Example:

// Corsair handles rate limits automatically
await corsair.amplitude.api.events.upload({
    events: [{ event_type: "page_view", user_id: "user-123" }], 
});

Authentication Errors

Triggers: HTTP 401 status, invalid API key

Behavior:

• Maximum retries: 0 (no retries)
• Fails immediately

How to Fix:

1. Verify your Amplitude API key is correct
2. Check the key has not been revoked in your Amplitude project settings
3. Ensure you're using the correct project's API key

Invalid Request Errors

Triggers: HTTP 400 status, malformed event data

Behavior:

• Maximum retries: 0 (no retries)

How to Fix:

1. Verify required fields are present on each event object
2. Check event property types match expected formats
3. Ensure user_id or device_id is present on each event

Network Errors

Triggers: Connection errors, timeouts

Behavior:

• Maximum retries: 3
• Uses exponential backoff

Custom Error Handlers

amplitude({
    errorHandlers: {
        INVALID_EVENT_SCHEMA: {
            match: (error) => {
                return error.message.includes("invalid_uploadtime"); 
            },
            handler: async (error, context) => {
                console.log("Invalid event timestamp detected");
                return {
                    maxRetries: 0,
                };
            },
        },
    },
})

For comprehensive error handling strategies, patterns, and best practices, see the Error Handling concepts page.