Oura Error Handlers

The Oura plugin includes built-in error handlers for common Oura 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.oura.api.summary.getSleep({
    start_date: "2024-01-01", 
    end_date: "2024-01-31",
});

Authentication Errors

Triggers: HTTP 401 status

Behavior:

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

How to Fix:

1. Verify your personal access token is valid
2. Generate a new token in your Oura account settings
3. Check the token has not been revoked

Permission Errors

Triggers: HTTP 403 status

Behavior:

• Maximum retries: 0 (no retries)

How to Fix:

1. Ensure your token has access to the requested data scope
2. Check that data sharing is enabled in Oura app settings

Default Handler

Triggers: Any unmatched error

Behavior:

• Maximum retries: 0 (no retries)

Custom Error Handlers

oura({
    errorHandlers: {
        SYNC_IN_PROGRESS: {
            match: (error) => {
                return error.message.includes("sync"); 
            },
            handler: async (error, context) => {
                return {
                    maxRetries: 3,
                    headersRetryAfterMs: 30000, 
                };
            },
        },
    },
})

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