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

# Errors

> How the API reports errors and how to handle them

## Conventions

The API uses standard HTTP status codes. The response body is JSON with `message` and optionally `code` / `errors`:

```json theme={null}
{
  "message": "Validation failed",
  "errors": {
    "email": "Invalid email",
    "password": "Minimum 8 characters"
  }
}
```

## Most common codes

| Status  | When it occurs                                          |
| ------- | ------------------------------------------------------- |
| **200** | Success                                                 |
| **201** | Resource created                                        |
| **204** | Success with no content (e.g. delete)                   |
| **400** | Bad request — malformed payload or invalid data         |
| **401** | Not authenticated (missing, invalid or expired token)   |
| **402** | Payment required — subscription expired                 |
| **403** | No permission for this endpoint                         |
| **404** | Resource not found                                      |
| **422** | Validation failed — body has `errors` per field         |
| **429** | Rate limit — slow down                                  |
| **500** | Internal error — retry; if it persists, contact support |

## Recommended handling

<CodeGroup>
  ```javascript Node theme={null}
  async function callApi(path, options) {
    const res = await fetch(`https://app.tarefy.com/nodeapi${path}`, options);

    if (res.status === 401) {
      // token expired → refresh and retry
      await refreshToken();
      return callApi(path, options);
    }

    if (res.status === 402) {
      throw new Error('Subscription expired — check billing');
    }

    if (!res.ok) {
      const body = await res.json();
      throw new Error(body.message || `HTTP ${res.status}`);
    }

    return res.json();
  }
  ```

  ```python Python theme={null}
  import requests

  def call_api(path, **kwargs):
      res = requests.request(
          url=f"https://app.tarefy.com/nodeapi{path}",
          **kwargs
      )
      if res.status_code == 401:
          # token expired
          refresh_token()
          return call_api(path, **kwargs)
      res.raise_for_status()
      return res.json()
  ```
</CodeGroup>