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
}

General Error Codes

These error codes are returned across all endpoints:

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

Recommended Approach

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

1
import { ExtendClient, ExtendError } from "extend-ai";
2
3
const client = new ExtendClient({ token: "your_api_key" });
4
5
try {
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.