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:

{
  "defined": false,
  "code": "NOT_FOUND",
  "status": 404,
  "message": "part not found"
}

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

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

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.

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.

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.