AthlEAT
Docs/athlete-nutrition-ai/Troubleshooting
Runbook

Troubleshooting

Common API errors and debugging

Objective

Objective

This runbook helps you diagnose and resolve common errors that athletes and end users may encounter while using the athlete-nutrition-ai app, covering sign-in failures, unexpected app behavior, and service outages.

Scope

Scope

This runbook covers HTTP errors and debugging steps for the following athlete-nutrition-ai app workflows:

In scope:

  • Sign-in and account access errors
  • Athlete profile setup and update failures
  • Training calendar connection issues
  • AI nutrition advisor chat errors
  • Shopping list generation failures
  • Subscription management errors
  • General HTTP 4xx and 5xx error patterns

Out of scope:

  • Bugs or crashes caused by your device or operating system
  • Third-party training calendar outages (e.g., failures originating from an external calendar service itself)
  • Billing disputes or payment processing issues (contact support directly for these)
  • Internet connectivity or network issues on your end
Prerequisites

Before working through this runbook, ensure you have the following:

  • An active athlete-nutrition-ai account — if you do not have one, sign up at the app's registration page before proceeding
  • The app installed and up to date on your device or, if using the web version, a supported browser with network request inspection available (e.g., Chrome DevTools or Firefox Developer Tools)
  • Access to the screen or message where the error occurred, including any error text, codes, or prompts displayed to you
  • Your login credentials for the account experiencing the issue — do not share your password in support tickets or public forums
  • A note of which environment you are using (the main app versus any beta or preview version) — confirm this in your account settings before debugging, as mixing versions is a common source of errors
  • Basic familiarity with how to screenshot or record your screen, and how to copy and share error messages from the app
Steps

Work through the steps below in order. Each step identifies a common failure category, shows you how to inspect it, and tells you what a successful resolution looks like.

Step 1 — Capture the full error details

Before attempting any fix, collect the complete error information. Partial information leads to incorrect diagnoses.

Action: Note the following when the error occurs:

  • The error message displayed on screen or returned by the app
  • Any error code shown (such as a number or short code like AUTH_EXPIRED)
  • The action you were performing when the error appeared (for example, logging in, viewing your nutrition plan, or generating a shopping list)
  • The approximate time the error occurred

If you are using a browser, open the browser console (F12 on most browsers) and note any error messages shown under the Console or Network tab.

Success looks like: You have a clear record of the error message, code, and context to reference in the steps below.

Step 2 — Resolve sign-in and authentication errors

An authentication error means the app could not verify your identity. This is most commonly caused by an expired session, incorrect credentials, or a sign-in issue.

Action: Check the following in order:

  1. Confirm you are using the correct email address and password for your account.
  2. If you have been logged into the app for an extended period without activity, your session may have expired. Sign out and sign back in to start a fresh session.
  3. Confirm you are signing in to the correct environment — if you have both a personal account and a team or organisation account, ensure you are using the right one.
  4. If you recently changed your password, make sure you are not using an old saved password from your browser or password manager.

Success looks like: You can sign in successfully and the app loads your profile and data as expected.

Step 3 — Resolve permission and access errors

A permission error means your account credentials are valid but you do not have access to the feature or content you are trying to use. This commonly occurs when:

  • Your subscription plan does not include the feature you are trying to use (for example, shopping list generation or advanced AI nutrition advice)
  • You are attempting to view or edit an athlete profile that does not belong to your account
  • Your account has been suspended

Action:

  1. Read the error message carefully — it will usually describe which feature or permission boundary is involved.
  2. Sign in to your account settings and confirm your subscription is active and includes the feature you are trying to access.
  3. Verify that any athlete profiles or training events you are viewing belong to your own account.

Success looks like: After confirming your subscription includes the feature, or correcting which profile you are viewing, the app loads the content successfully.

Step 4 — Resolve "not found" errors

A "not found" error means the app cannot locate the content you are trying to access. Common causes include:

  • Following an old or bookmarked link to content that no longer exists
  • Attempting to view a training event or shopping list that has been deleted
  • A synced calendar event that is no longer available in the connected calendar

Action:

  1. Navigate back to the main section of the app (such as your dashboard or training calendar) rather than using a direct link or bookmark.
  2. Check whether the item you are looking for — such as a training event or shopping list — still exists by browsing to it from the home screen.
  3. If you connected an external training calendar, confirm that the event still exists in the original calendar app and that the calendar sync is active.

Success looks like: You locate the correct content by navigating through the app, or confirm the item no longer exists and create a new one if needed.

Step 5 — Resolve form and data entry errors

A validation error means the app received information you submitted but could not accept it because something was missing or incorrectly formatted. This is common when setting up or updating your athlete profile, connecting a training calendar, or using the AI nutrition advisor.

Action:

  1. Read the error message carefully — it will usually identify which field or fields need attention.
  2. Check that all required fields are filled in. Look for any fields marked as required that may have been left blank.
  3. Check the format of any dates, numbers, or selections:
    • Dates should be entered in the format the app requests
    • Height, weight, and other numeric fields should be numbers only, without units typed in the field unless the app asks for them
    • Dropdown selections such as dietary preferences or sport type must be chosen from the provided options rather than typed in
  4. If you are connecting a training calendar, try disconnecting and reconnecting the calendar to refresh the connection.

Success looks like: After correcting the flagged fields and resubmitting, the app accepts the information and continues.

Step 6 — Resolve "too many requests" errors

This error means you have performed actions too quickly for the app to process in your current subscription tier. This can occur when generating multiple shopping lists or making many requests in quick succession.

Action:

  1. Wait a short time — usually one to two minutes — before trying again.
  2. Avoid triggering the same action repeatedly in quick succession (for example, tapping a button multiple times while waiting for a response).
  3. If you regularly need to perform high volumes of actions and are hitting this limit frequently, review the available subscription tiers in your account settings to see whether an upgraded plan better suits your usage.

Success looks like: After waiting briefly and trying again, the action completes successfully.

Step 7 — Resolve server errors

A server error means something went wrong on the athlete-nutrition-ai side. You cannot resolve these by changing what you do in the app, but you can confirm whether the issue is temporary.

Action:

  1. Note the error code or message shown on screen and the time it occurred — you will need this if you contact support.
  2. Wait 60 seconds and try the action again.
  3. Check the athlete-nutrition-ai status page for any known issues or ongoing incidents.
  4. If the error persists for more than 5 minutes or is preventing you from using a critical feature, proceed to the Escalation section.

Success looks like: The action succeeds when retried, confirming the error was temporary. If it does not resolve, escalation is the next step.

Step 8 — Validate your end-to-end workflow

After resolving an individual error, confirm that everything you rely on in the app is working correctly by running through your typical workflow in sequence:

  1. Sign out and sign back in to confirm your session is healthy.
  2. Review your athlete profile to ensure your details are up to date.
  3. Check your training calendar to confirm upcoming events are visible.
  4. Send a message to the AI nutrition advisor and confirm you receive a response.
  5. Generate a shopping list for an upcoming event.

Success looks like: Each step completes without errors and the app displays your data and responses as expected.

Verification

After completing the steps above, confirm resolution using the following observable outcomes:

  • No repeated error codes: The endpoint that was previously failing now consistently returns a 2xx status code across at least three consecutive requests.
  • Response body is well-formed: The JSON response body contains the expected fields for the endpoint (e.g., a generated shopping list contains item arrays, an athlete profile response contains the profile fields you submitted).
  • Authentication is stable: Your access token successfully authenticates requests without needing to be replaced immediately, confirming it is not expired or corrupted.
  • AI advisor responds coherently: If you were debugging a chat endpoint failure, the advisor returns a contextually relevant nutrition recommendation referencing the athlete's training events and dietary preferences — not a generic error message.
  • Logs are clean: Your application logs show no recurrence of the error status codes documented in this runbook for the affected endpoint over a 10-minute observation window after your fix.

If any of these outcomes are not met, revisit the relevant step above or proceed to escalation.

Rollback

The steps in this runbook are diagnostic and corrective in nature — they do not modify your production data or infrastructure by default. However, if any of the following corrective actions were taken and need to be reversed, follow the guidance below:

If you rotated your API key or access token: If your old token is still within its validity window and you rotated it unnecessarily, you will need to update all services using the new token. There is no mechanism to restore a previously issued token — ensure any new token is propagated to all integration points before invalidating the old one.

If you modified your athlete profile payload to resolve a 422 error: If the change produced unintended side effects (e.g., overwriting dietary preferences), re-send a PUT or PATCH request to the athlete profile endpoint with the correct original values to restore them.

If you changed your subscription tier to resolve a 403 error: Subscription changes may have billing implications. Contact athlete-nutrition-ai support to discuss reverting a tier change if it was made in error.

If you disconnected and reconnected a training calendar to resolve a connection error: Verify that all previously synced training events are still visible via the upcoming events endpoint after reconnection. If events are missing, reconnect the calendar again and allow time for the sync to complete.

Escalation

If you have followed all steps in this runbook and the error persists, escalate using the guidance below.

When to escalate:

  • A 500 or 503 error persists for more than 5 minutes with no active status page incident
  • You are receiving consistent 4xx errors that do not match any described cause after careful review
  • A previously working integration began failing without any change on your side

Who to contact: Reach the athlete-nutrition-ai developer support team through the support portal in your developer dashboard.

What to include in your escalation: Provide the following information to enable rapid diagnosis — incomplete reports significantly delay resolution:

  1. X-Request-ID (or equivalent trace header) from one or more failing responses
  2. Full HTTP request details: method, endpoint path, and sanitized request headers (remove your actual token value — replace it with REDACTED)
  3. Full HTTP response: status code, response headers, and complete response body
  4. Timestamp of the first occurrence and approximate frequency (e.g., "every request since 14:00 UTC")
  5. Environment: whether you are targeting production or sandbox
  6. Affected workflow: which step in the workflow is failing (e.g., "shopping list generation after connecting a training calendar")
  7. Steps already taken: a summary of which runbook steps you completed and their outcomes