Error Codes

When the Extend API returns an error, the response includes an error object with a code, message, and retryable field to help you understand what went wrong and how to handle it. A requestId is also included when available. For validation errors, a docUrl field may also be present with a link to relevant documentation.

Error Response Structure

1{
2  "code": "INVALID_REQUEST",
3  "message": "Non-nullable primitive type \"string\" is not allowed. Use [\"string\", \"null\"] instead of \"string\".; Path: schema.properties.name",
4  "retryable": false,
5  "requestId": "req_Xj8mK2pL9nR4vT7qY5wZ",
6  "docUrl": "https://docs.extend.ai/2026-02-09/product/extraction/schema#primitive-schema"
7}
FieldTypeDescription
codestringError code for programmatic handling
messagestringHuman-readable error description
retryablebooleanWhether the request can be retried with exponential backoff
requestIdstringUnique identifier for support purposes
docUrlstring (optional)Link to relevant documentation for resolving the error

General Error Codes

These error codes are returned across all endpoints:

Error CodeDescriptionRetryable
INVALID_REQUESTThe request body or parameters are invalid (e.g. missing required fields, validation errors).No
UNAUTHORIZEDAuthentication failed — the API key is missing, malformed, or invalid.No
NOT_FOUNDThe requested resource does not exist.No
RATE_LIMIT_EXCEEDEDToo many requests. Back off and retry.Yes
USAGE_BLOCKEDOrganization usage is blocked due to insufficient credits.No
ENDPOINT_REMOVEDThe endpoint has been deprecated and removed. The message will indicate the replacement.No
INTERNAL_ERRORAn unexpected server error occurred.Yes

Domain-specific error codes (e.g. for parse runs, extract runs) are also returned — use the retryable field to determine if a request can be retried, and the message field for debugging.

Handling Errors

  1. Check retryable to determine if the request can be retried
  2. Use the code for specific programmatic handling
  3. Log the requestId for debugging and support requests
  4. Display the message to users when appropriate
  5. Check docUrl for a link to documentation that can help resolve the error

Example Error Handling

1import { ExtendClient, ExtendError } from "extend-ai";
2
3const client = new ExtendClient({ token: "your_api_key" });
4
5try {
6  const result = await client.extract({
7    extractor: { id: "your_extractor_id" },
8    file: { url: "https://example.com/document.pdf" },
9  });
10} catch (error) {
11  if (error instanceof ExtendError) {
12    // error.body contains the parsed JSON response
13    const body = error.body as {
14      code: string;
15      message: string;
16      retryable: boolean;
17      requestId: string;
18      docUrl?: string;
19    };
20
21    if (body.retryable) {
22      // Retry with exponential backoff
23      await sleep(1000);
24      return retry();
25    }
26
27    // Log error details for debugging
28    console.error(`API error: ${body.code}, message: ${body.message}, requestId: ${body.requestId}`);
29
30    // If a documentation link is provided, log it for easy reference
31    if (body.docUrl) {
32      console.error(`See documentation: ${body.docUrl}`);
33    }
34  }
35  throw error;
36}

Getting Help

When contacting support about an error, always include:

  1. The requestId from the error response
  2. The timestamp of when the error occurred
  3. The endpoint you were calling
  4. The error code

This information helps us quickly identify and resolve issues.