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

# Error Handling

> Understand API errors and how to handle them

For HTTP status summaries, subscription gates, and rate-limit headers, see [API overview](/api-reference/overview).

## Error Response Format

All errors follow a consistent format:

```json theme={null}
{
  "status": "failed",
  "message": "Error description"
}
```

## HTTP Status Codes

<ResponseField name="200 OK" type="object">
  Request successful
</ResponseField>

<ResponseField name="201 Created" type="object">
  Resource created successfully
</ResponseField>

<ResponseField name="400 Bad Request" type="object">
  Invalid request parameters or malformed request body
</ResponseField>

<ResponseField name="401 Unauthorized" type="object">
  Invalid or missing API key
</ResponseField>

<ResponseField name="403 Forbidden" type="object">
  Business does not have an active subscription required for the Developer API
</ResponseField>

<ResponseField name="404 Not Found" type="object">
  Resource not found
</ResponseField>

<ResponseField name="500 Internal Server Error" type="object">
  Server error. Please contact support if this persists.
</ResponseField>

## Common Errors

### Invalid API Key

<ResponseField name="401 Unauthorized" type="object">
  ```json theme={null}
  {
    "status": "failed",
    "message": "Invalid API key. Please check your API key and try again."
  }
  ```
</ResponseField>

**Solution**: Verify your API key is correct and included in the request header.

### No Active Subscription

<ResponseField name="403 Forbidden" type="object">
  ```json theme={null}
  {
    "status": "failed",
    "message": "Your business must have an active subscription to use the Developer API. Please upgrade your subscription to continue."
  }
  ```
</ResponseField>

**Solution**: The Developer API requires a paid subscription. Upgrade your subscription plan to continue using the API.

### Resource Not Found

<ResponseField name="404 Not Found" type="object">
  ```json theme={null}
  {
    "status": "failed",
    "message": "Invoice not found"
  }
  ```
</ResponseField>

**Solution**: Check that the UUID or source\_uuid exists and is correct.

### Invalid Request Body

<ResponseField name="400 Bad Request" type="object">
  ```json theme={null}
  {
    "status": "failed",
    "message": "Invalid request body. Missing required field: prompt"
  }
  ```
</ResponseField>

**Solution**: Ensure all required fields are included in your request body.

## Rate Limiting

API rate limits may apply. Check response headers for rate limit information:

* `X-RateLimit-Limit`: Maximum requests per time window
* `X-RateLimit-Remaining`: Remaining requests in current window
* `X-RateLimit-Reset`: Time when rate limit resets

<Warning>
  If you exceed rate limits, you'll receive a 429 Too Many Requests response. Implement exponential backoff in your integration.
</Warning>

## UUID Resolution

All update and delete operations support both `uuid` and `source_uuid` for record identification. The API automatically checks both fields when looking up records.

**Example:**

* If you have a record with `uuid: "abc-123"` and `source_uuid: "xyz-789"`
* You can use either `abc-123` or `xyz-789` in the endpoint URL
* Both will resolve to the same record

## Best Practices

1. **Always check status codes** before processing responses
2. **Handle errors gracefully** with appropriate user feedback
3. **Implement retry logic** for transient errors (5xx status codes)
4. **Respect rate limits** by implementing request throttling
5. **Log errors** for debugging and monitoring