> ## Documentation Index
> Fetch the complete documentation index at: https://docs.teamcaredental.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Error Codes and Troubleshooting Guide

> TeamCare APIs return standard HTTP error codes. Learn what 400, 401, 422, 429, and 500 responses mean and how to handle them in your integration.

TeamCare APIs use standard HTTP status codes to indicate the outcome of each request. Understanding these codes helps you diagnose issues quickly and respond appropriately in your integration.

Every error response includes a relevant status code. For rate limit errors, the response also includes a `Retry-After` header so you know when it is safe to retry.

## Error codes

| HTTP Status | Name                  | Description                                                                  | What to do                                                                                             |
| ----------- | --------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **400**     | Bad Request           | The request syntax or parameters are invalid.                                | Check the request body and query parameters for formatting errors or missing required fields.          |
| **401**     | Unauthorized          | The request is missing a valid Bearer token, or the token has expired.       | Re-authenticate with the token endpoint and include the new JWT in the `Authorization: Bearer` header. |
| **422**     | Unprocessable Entity  | The request was understood, but one or more fields are semantically invalid. | Review field values and data types. Ensure dates are in the expected format and filters are valid.     |
| **429**     | Too Many Requests     | You have exceeded the rate limit for the current window.                     | Read the `Retry-After` header and wait that many seconds before retrying the request.                  |
| **500**     | Internal Server Error | An unexpected error occurred on the TeamCare server.                         | Retry after a short delay. Contact TeamCare support if the error persists.                             |

## Handling retries

For transient errors such as 429 and 500, implement retry logic with exponential backoff, respecting the `Retry-After` header on 429 responses.

<Note>
  All 429 responses include a `Retry-After` header with a value from 1 to 60. You must wait that many seconds before the next request, because rejected requests still count against the current rate limit window.
</Note>

TeamCare APIs use standard HTTP status codes to indicate the outcome of each request. Understanding these codes helps you diagnose issues quickly and respond appropriately in your integration.

Every error response includes a relevant status code. For rate limit errors, the response also includes a `Retry-After` header so you know when it is safe to retry.

## Error codes

| HTTP Status | Name                  | Description                                                                  | What to do                                                                                             |
| ----------- | --------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **400**     | Bad Request           | The request syntax or parameters are invalid.                                | Check the request body and query parameters for formatting errors or missing required fields.          |
| **401**     | Unauthorized          | The request is missing a valid Bearer token, or the token has expired.       | Re-authenticate with the token endpoint and include the new JWT in the `Authorization: Bearer` header. |
| **422**     | Unprocessable Entity  | The request was understood, but one or more fields are semantically invalid. | Review field values and data types. Ensure dates are in the expected format and filters are valid.     |
| **429**     | Too Many Requests     | You have exceeded the rate limit for the current window.                     | Read the `Retry-After` header and wait that many seconds before retrying the request.                  |
| **500**     | Internal Server Error | An unexpected error occurred on the TeamCare server.                         | Retry after a short delay. Contact TeamCare support if the error persists.                             |

## Handling retries

For transient errors such as 429 and 500, implement retry logic with exponential backoff, respecting the `Retry-After` header on 429 responses.

<Note>
  All 429 responses include a `Retry-After` header with a value from 1 to 60. You must wait that many seconds before the next request, because rejected requests still count against the current rate limit window.
</Note>