Errors

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:

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

number

The HTTP status code, repeated in the body for convenience.

string

A short machine-readable label for the error class (for example "Not Found" or "Bad Request").

string | string[]

A human-readable description of the error. For validation errors this may be an array of strings, one per invalid field.

string

ISO 8601 datetime of when the error occurred.

string

The request path that produced the error.

Validation Error Example

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

{
  "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.
500	Internal Server Error	An unexpected error occurred on the server. Retrying after a short delay is appropriate.

Handling Errors

JavaScript
Python

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();
}

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()

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:

The resource ID is correct.
The resource belongs to the organization associated with your API token.
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 or contact support.

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

Overview

Endpoints

Error Response Format

Validation Error Example

Status Code Reference

Handling Errors

404 vs 403: Resource Visibility

Server Errors (5xx)

​Error Response Format

​Validation Error Example

​Status Code Reference

​Handling Errors

​404 vs 403: Resource Visibility

​Server Errors (5xx)

Error Response Format

Validation Error Example

Status Code Reference

Handling Errors

404 vs 403: Resource Visibility

Server Errors (5xx)