Error handling

The MotifSDKError shape, common failures, and handling patterns.

The TypeScript SDK throws MotifSDKError for failed API responses and for SDK configuration errors. Catch it at your integration boundaries.

---

Error shape

import { MotifSDKError } from '@motif-ai/sdk'

try {
  await motif.users.get('invalid_id')
} catch (error) {
  if (error instanceof MotifSDKError) {
    console.error(error.statusCode)  // HTTP status, when a response was received
    console.error(error.message)     // human-readable message
    console.error(error.response)    // raw response payload
  }
  throw error
}

---

Common failures

Status	Typical cause	Handling
400	Invalid input, or missing x-user-id on a user-scoped call	Validate request data and user context before calling
401	Missing or invalid API key	Check secret configuration and key status
403	Organization inactive, key not org-linked, or cross-org access	Confirm the org is active and the user belongs to it
404	User, portfolio, or strategy not found	Re-fetch state before retrying
429	Rate limit exceeded	Retry later with backoff
500	Motif service error	Retry idempotent operations, and contact support if it persists

---

Best practices

• Catch MotifSDKError at integration boundaries and log statusCode plus response.

• Branch on the HTTP statusCode rather than message strings, since messages may change.

• Call motif.forUser(userId) only after creating or retrieving the Motif user id.

• Treat write retries as potentially duplicate unless the endpoint is documented as idempotent.