Skip to main content
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"
}
​
statusCode
number
The HTTP status code, repeated in the body for convenience.
​
error
string
A short machine-readable label for the error class (for example "Not Found" or "Bad Request").
​
message
string | string[]
A human-readable description of the error. For validation errors this may be an array of strings, one per invalid field.
​
timestamp
string
ISO 8601 datetime of when the error occurred.
​
path
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

CodeNameWhen it occurs
200OKThe request succeeded and a result was returned.
201CreatedA resource was successfully created (POST requests that create a new record).
400Bad RequestThe request body or query parameters failed validation.
401UnauthorizedNo credentials were provided, or the provided API token is invalid or revoked.
403ForbiddenValid credentials were provided but do not have permission for this action.
404Not FoundThe requested resource does not exist or does not belong to your organization.
409ConflictThe request conflicts with existing data (for example, a duplicate key name).
422Unprocessable EntityThe request was well-formed but contained semantic errors (for example, unsupported language).
429Too Many RequestsThe rate limit for this token or endpoint has been exceeded. See Rate Limits.
500Internal Server ErrorAn unexpected error occurred on the server. Retrying after a short delay is appropriate.

​
Handling Errors

async function apiRequest(path, options = {}) {
  const response = await fetch(`https://api.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();
}

​
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 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.