Error responses

Overview

Every error response from the API is an RFC 9457 problem document, served with Content-Type: application/problem+json.

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/prod/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName"
    }
  ]
}

Branch your error handling on code, not on detail or title. code is a stable public contract — new codes may be added, but existing ones are never renamed or repurposed. detail is human-facing prose and can change at any time.

Fields

Field	Type	Description
type	string	URI identifying the problem type, e.g. `https://errors.file.ai/validation-failed`.
title	string	Stable, human-readable summary of the problem type.
status	number	HTTP status code, repeated in the body.
detail	string	Human-readable explanation specific to this occurrence.
instance	string	URI reference for this occurrence — the full request path, including the `/prod` prefix.
code	string	Stable machine-readable error code — branch on this.
requestId	string	Correlation id for the request. Quote it in support requests.
errors	array	Field-level violations. Populated on validation errors, `[]` otherwise.
retryAfter	number	Seconds until you may retry. Present on `429` only.

Field-level violations

Each entry in errors describes one offending field:

Field	Type	Description
code	string	Violation code, e.g. `REQUIRED`.
detail	string	What was wrong, e.g. `must not be empty`.
pointer	string	JSON Pointer to the offending body field, e.g. `#/fileName`.
parameter	string	Name of the offending query or header parameter, e.g. `limit`.

pointer is set for body fields and parameter for query/header parameters — an entry carries whichever one applies.

Error codes

Code	Status	Title	When it happens
`BAD_REQUEST`	400	Bad request	The request could not be processed as sent.
`UNAUTHENTICATED`	401	Unauthenticated	The `x-api-key` header is missing or the key is invalid.
`FORBIDDEN`	403	Forbidden	The key is inactive, or lacks access to the resource.
`READONLY_KEY`	403	Read-only API key	A read-only key was used on a write endpoint.
`NOT_FOUND`	404	Not found	The referenced resource does not exist in this workspace.
`IDEMPOTENT_REQUEST_IN_PROGRESS`	409	Idempotent request in progress	An earlier request with the same `Idempotency-Key` is still running.
`VALIDATION_FAILED`	422	Validation failed	One or more parameters or body fields are invalid. See `errors[]`.
`IDEMPOTENCY_KEY_REUSED`	422	Idempotency key reused	The same `Idempotency-Key` was reused with a different request body.
`RATE_LIMITED`	429	Too many requests	The rate limit was exceeded. Wait `retryAfter` seconds.
`INTERNAL_ERROR`	500	Internal server error	Unexpected server-side failure. Safe to retry.

Legacy fields

Problem documents also carry three deprecated keys for backwards compatibility with integrations written before RFC 9457 responses were introduced:

Legacy field	Use instead
`message`	`detail` / `title`
`error`	`title`
`statusCode`	`status`

The legacy keys are deprecated and will be removed in a future version. Migrate to detail, title, and status.

Handling errors

Retrying safely

429 and 500 are safe to retry. On 429, wait retryAfter seconds; for 500, back off exponentially. Send an Idempotency-Key on write endpoints so a retry cannot apply the same change twice.

Do not retry

400, 401, 403, 404, and 422 describe a problem with the request itself. Retrying without changing anything returns the same error.

Reporting a problem

Include the requestId and code when contacting support@file.ai — requestId correlates your call to our server-side logs.

fileAI API

Key Functions

Endpoints

Overview

Fields

Field-level violations

Error codes

Legacy fields

Handling errors

​Overview

​Fields

​Field-level violations

​Error codes

​Legacy fields

​Handling errors

Overview

Fields

Field-level violations

Error codes

Legacy fields

Handling errors