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

# Errors

> Understand Entri API error codes and how to handle them.

The Entri API uses standard HTTP status codes to communicate the outcome of every request. Status codes in the `2xx` range indicate success. Codes in the `4xx` range indicate a problem with the request (something the caller can fix). Codes in the `5xx` range indicate a problem on the server side.

## Error Response Format

All error responses return a JSON body with the following structure:

```json theme={null}
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Project not found",
  "timestamp": "2025-03-02T14:30:00.000Z",
  "path": "/api/projects/proj_abc123"
}
```

<ResponseField name="statusCode" type="number">
  The HTTP status code, repeated in the body for convenience.
</ResponseField>

<ResponseField name="error" type="string">
  A short machine-readable label for the error class (for example `"Not Found"` or `"Bad Request"`).
</ResponseField>

<ResponseField name="message" type="string | string[]">
  A human-readable description of the error. For validation errors this may be an array of strings, one per invalid field.
</ResponseField>

<ResponseField name="timestamp" type="string">
  ISO 8601 datetime of when the error occurred.
</ResponseField>

<ResponseField name="path" type="string">
  The request path that produced the error.
</ResponseField>

### Validation Error Example

When the request body fails validation, `message` contains one entry per failing field:

```json theme={null}
{
  "statusCode": 400,
  "message": [
    "name must be a string",
    "sourceLanguage should not be empty"
  ],
  "error": "Bad Request"
}
```

## Status Code Reference

| Code | Name                  | When it occurs                                                                                              |
| ---- | --------------------- | ----------------------------------------------------------------------------------------------------------- |
| 200  | OK                    | The request succeeded and a result was returned.                                                            |
| 201  | Created               | A resource was successfully created (POST requests that create a new record).                               |
| 400  | Bad Request           | The request body or query parameters failed validation.                                                     |
| 401  | Unauthorized          | No credentials were provided, or the provided API token is invalid or revoked.                              |
| 403  | Forbidden             | Valid credentials were provided but do not have permission for this action.                                 |
| 404  | Not Found             | The requested resource does not exist or does not belong to your organization.                              |
| 409  | Conflict              | The request conflicts with existing data (for example, a duplicate key name).                               |
| 422  | Unprocessable Entity  | The request was well-formed but contained semantic errors (for example, unsupported language).              |
| 429  | Too Many Requests     | The rate limit for this token or endpoint has been exceeded. See [Rate Limits](/api-reference/rate-limits). |
| 500  | Internal Server Error | An unexpected error occurred on the server. Retrying after a short delay is appropriate.                    |

## Handling Errors

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    async function apiRequest(path, options = {}) {
      const response = await fetch(`https://app.nt3.io/api${path}`, {
        ...options,
        headers: {
          "X-API-Key": process.env.ENTRI_API_KEY,
          "Content-Type": "application/json",
          ...options.headers,
        },
      });

      if (!response.ok) {
        const error = await response.json();

        if (response.status === 401) {
          throw new Error("Invalid or missing API token");
        }

        if (response.status === 429) {
          const retryAfter = response.headers.get("Retry-After");
          throw new Error(`Rate limit exceeded. Retry after ${retryAfter}s`);
        }

        const message = Array.isArray(error.message)
          ? error.message.join(", ")
          : error.message;
        throw new Error(`API error ${response.status}: ${message}`);
      }

      return response.json();
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import httpx

    def api_request(path: str, **kwargs):
        headers = {
            "X-API-Key": "entri_your_token_here",
            "Content-Type": "application/json",
        }

        with httpx.Client(base_url="https://app.nt3.io/api") as client:
            response = client.request(
                kwargs.pop("method", "GET"),
                path,
                headers=headers,
                **kwargs,
            )

        if response.status_code == 401:
            raise ValueError("Invalid or missing API token")

        if response.status_code == 429:
            retry_after = response.headers.get("Retry-After", "unknown")
            raise RuntimeError(f"Rate limit exceeded. Retry after {retry_after}s")

        response.raise_for_status()
        return response.json()
    ```
  </Tab>
</Tabs>

## 404 vs 403: Resource Visibility

For security reasons, the API returns `404 Not Found` in some situations where a resource exists but your token does not have access to it. This prevents information leakage about resources belonging to other organizations.

If you receive an unexpected `404`, verify that:

1. The resource ID is correct.
2. The resource belongs to the organization associated with your API token.
3. The resource has not been deleted or archived.

## Server Errors (5xx)

If you receive a `500 Internal Server Error`, the request may succeed if retried. Use exponential backoff when retrying server errors. If the error persists, check the [status page](https://status.entri.io) or contact support.

<Note>
  Do not retry `4xx` errors automatically — they indicate a problem with the request itself, not a transient server issue. Fix the request before retrying.
</Note>