> ## Documentation Index
> Fetch the complete documentation index at: https://developer.fieldnode.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

The Fieldnode API returns failures as JSON with a stable shape across every endpoint. The HTTP status
is set from the error `code`.

## Error JSON format

Typical error response:

```json theme={null}
{
  "defined": false,
  "code": "NOT_FOUND",
  "status": 404,
  "message": "part not found"
}
```

When a procedure declares typed error data, the payload is included under `data`:

```json theme={null}
{
  "defined": true,
  "code": "PRECONDITION_FAILED",
  "status": 412,
  "message": "part is published",
  "data": { "partId": "01J..." }
}
```

## Fields

* `code` — Machine-readable error code in `SCREAMING_SNAKE_CASE` (see table below).
* `status` — HTTP status code, also reflected on the response itself.
* `message` — Human-readable description of the failure.
* `defined` — `true` when the error was declared on the procedure contract (so `data` is typed); `false` for generic/uncaught errors.
* `data` — Optional, procedure-specific payload. Only present for `defined: true` errors that declare a data schema.

## HTTP status and error code mapping

| Code                     | HTTP status | Description                                                       |
| ------------------------ | ----------- | ----------------------------------------------------------------- |
| `BAD_REQUEST`            | `400`       | Request is malformed or fails input validation.                   |
| `UNAUTHORIZED`           | `401`       | Request is missing valid authentication credentials (PAT).        |
| `FORBIDDEN`              | `403`       | Caller is authenticated but not allowed to perform the operation. |
| `NOT_FOUND`              | `404`       | Requested resource was not found.                                 |
| `METHOD_NOT_SUPPORTED`   | `405`       | HTTP method is not supported for this route.                      |
| `NOT_ACCEPTABLE`         | `406`       | Server cannot produce a response matching the `Accept` header.    |
| `TIMEOUT`                | `408`       | The server timed out waiting for the request.                     |
| `CONFLICT`               | `409`       | Request conflicts with current resource state.                    |
| `PRECONDITION_FAILED`    | `412`       | Operation preconditions are not met.                              |
| `PAYLOAD_TOO_LARGE`      | `413`       | Request body exceeds the allowed size.                            |
| `UNSUPPORTED_MEDIA_TYPE` | `415`       | Request `Content-Type` is not supported.                          |
| `UNPROCESSABLE_CONTENT`  | `422`       | Request is well-formed but semantically invalid.                  |
| `TOO_MANY_REQUESTS`      | `429`       | Rate limit or quota exceeded.                                     |
| `CLIENT_CLOSED_REQUEST`  | `499`       | Client closed the connection before the response completed.       |
| `INTERNAL_SERVER_ERROR`  | `500`       | Unexpected server error.                                          |
| `NOT_IMPLEMENTED`        | `501`       | Operation is not implemented.                                     |
| `BAD_GATEWAY`            | `502`       | An upstream dependency returned an invalid response.              |
| `SERVICE_UNAVAILABLE`    | `503`       | Service is temporarily unavailable; retries may succeed.          |
| `GATEWAY_TIMEOUT`        | `504`       | An upstream dependency timed out.                                 |

## Notes

* Use `code` for programmatic behavior (retry, prompt login, user messaging); the HTTP `status` mirrors it.
* Treat `message` as informational — do not parse it for control flow.
* Only inspect `data` when `defined` is `true`; for undeclared failures the field is absent.
* Input validation failures (Zod) surface as `BAD_REQUEST` with details about the offending fields in `data`.
* `499` (`CLIENT_CLOSED_REQUEST`) is not part of the standard HTTP status registry but is the conventional code for client-aborted requests.