Errors and troubleshooting

Handle API errors

The client is built on axios, so failed calls throw an error with a full HTTP response attached:

try {
  const { data } = await profileApi.mainApiV1GetMyProfileInfoGet();
  console.log(data);
} catch (error: any) {
  if (error?.response) {
    const status = error.response.status;
    if (status === 401) {
      console.error('The token is missing, invalid, disabled, or expired');
    } else if (status === 403) {
      console.error('The account or subscription does not allow this operation');
    } else if (status === 429) {
      console.error('Rate limit reached; retry after the response window');
    } else {
      console.error(status, error.response.data);
    }
  } else {
    console.error('Network failure:', error?.message);
  }
}

Every successful call also returns { status, data, headers, config }, so you can inspect metadata without throwing:

const { status, data } = await statisticsApi.mainApiV1GetMyDashboardStatsGet();
console.log(`HTTP ${status}`, data);

Common statuses

Status	Meaning	Action
400	invalid request model or field value	correct the request before retrying
401	missing, invalid, disabled, or expired token	verify or rotate the token
403	account or subscription does not allow the request	use an allowed history period or upgrade access
404	resource or token UUID does not exist	verify the identifier
409	operation conflicts with current state	inspect the response body
429	gateway rate limit reached	retry after the rate-limit window
5xx	temporary gateway or service failure	retry with exponential backoff

Timeouts and network failures

When error.response is undefined, the request never reached the gateway. Check local connectivity, proxy settings, and DNS before retrying.

For production integrations, wrap SDK calls in a retry helper with exponential backoff and honor Retry-After on 429 responses.

Verify your setup

If every call fails with 401:

1. confirm the environment variable is set in the process running your code
2. check that the token starts with analog-wakatime_live_ (or use a fresh session JWT)
3. create a new personal API token if the old one was disabled or deleted