Authentication & Errors

API Key Authentication

Each API key belongs to an environment. Use a key from the environment that contains your templates and filters, and use a key from that same environment to read your extraction jobs.

Create And Manage A Key

1. Select your environment in the app.
2. Open Dashboard > API Keys and select Create New Key.
3. Name the key after the backend or integration that will use it.
4. Copy the key when it appears. The full value is shown once.
5. Store it in your backend’s secret manager or protected configuration.

Keep API keys out of browser code, source control, and logs. When replacing a key, update your callers to use the new key before deleting the old one.

Send this header on every extraction API request:

Authorization: api-key <environment-api-key>

For example:

curl "https://api.terrafai.com/api/v1/extraction-jobs/$JOB_ID" \
  -H "Authorization: api-key $API_KEY"

Optional Request Headers

Header	Use it for
Idempotency-Key	Retrying an async upload after a timeout or interrupted connection. See Safe Retries.
X-Client-Reference	Linking an upload and its usage to a record in your system. See Client Reference.

Successful upload responses include a generated requestId. Save it, and the async job.id when applicable, to help trace the request later.

Handle Errors

Check the HTTP status before reading extraction data. An API error usually includes a code, a message, and a request ID:

{
  "success": false,
  "error": {
    "code": "JOB_NOT_FOUND",
    "message": "Extraction job not found.",
    "requestId": "request-id"
  }
}

Use error.code to choose how your application responds. The message explains the problem; its wording may change. Keep the request ID when one is available so support can help investigate.

Handle empty or non-JSON error bodies too, using the HTTP status as your fallback. For 429 or 503, honor the Retry-After header when supplied. It can contain a delay in seconds or an HTTP date.

Status Codes

Status	What to do
400	Correct the request using the error message and the endpoint’s documented fields.
401	Check the api-key authorization header and confirm the key is active.
402	Check your environment’s remaining monthly page allowance. Increase the allowance or wait for it to reset.
404	Check the template or filter name, or the job ID and environment. An expired job also returns 404.
409	Read the error code or message. An idempotency key may conflict with the request, an upload may still be in progress, or a result may be waiting for processing or review.
410	The completed result has expired. Retrieve and store future results before retention ends.
413	Reduce the JSON request size or use multipart upload.
429	Slow down requests and wait for Retry-After when supplied.
500, 503, 504	The request failed or timed out. Follow the retry guidance below.

Request Errors

Code	What to do
MISSING_API_KEY, UNSUPPORTED_AUTH_SCHEME	Send Authorization: api-key <environment-api-key>.
INVALID_API_KEY	Use an active key from the correct environment.
INVALID_FILE_TYPE, FILE_TYPE_MISMATCH	Use a supported file format with a matching MIME type.
FILE_TOO_LARGE	Reduce or split the file. The error message includes the active file size limit.
TOO_MANY_FILES	Send one file per request.
IDEMPOTENCY_KEY_CONFLICT	Retry the original file and settings, or use a new key for new work. See Key Conflicts.
MONTHLY_PAGE_LIMIT_EXCEEDED	Increase the page allowance or wait for the monthly reset.
PAGE_QUOTA_RESERVATION_CONFLICT	Retry the same request.

See Files And Upload Limits for accepted formats, Asynchronous Extraction for job errors, and Webhooks for webhook setup errors.

Retry An Interrupted Request

If an async upload times out, the job may already have been created. Retry the same file and settings with the same Idempotency-Key within the replay window. Once you have a job ID, use it to check status and retrieve the result.

A synchronous retry can process the document again. Use async jobs with an idempotency key when your integration needs to recover safely from an interrupted upload.