Errors

Errors use OpenAI’s error format, so the OpenAI SDKs raise the exception you’d expect (AuthenticationError, NotFoundError, and so on):

{
  "error": {
    "message": "The model 'acme/model:Q4_K_M' is disabled for your organization.",
    "type": "permission_error",
    "param": "model",
    "code": "model_disabled"
  }
}

Look at code to decide what to do. For problems with a specific field, param names it, for example messages[2].content.

Summary

Status	type	code	Retry?
400	invalid_request_error	missing_required_parameter, invalid_value, unsupported_parameter, unsupported_content_part, unsupported_by_node	No, fix the request
401	authentication_error	none	No
403	permission_error	model_disabled	No
404	invalid_request_error	model_not_found, unknown_url	No
500	server_error	none	Yes
502	server_error	node_error	Yes
503	server_error	model_unavailable	Yes
504	timeout_error	timeout	Yes

Nodea doesn’t currently apply rate limits, so you won’t receive 429.

Request errors (400)

missing_required_parameter

A required field is missing, for example: you must provide a ‘model’ parameter.

invalid_value

A field has the wrong type or is out of range, the body isn’t valid JSON, or messages is empty. Also returned for tool_choice: "required" and for a tool_choice that names a specific function, which aren’t supported.

unsupported_parameter

You sent a field that Nodea rejects, such as prediction, audio or parallel_tool_calls: false. See Rejected. Remove the field.

unsupported_content_part

A message contains image, audio or file content. Nodea accepts text only.

unsupported_by_node

The field is supported, but the devices serving this model run a version of the Nodea app that doesn’t support it. See Depends on the device. Update the desktop app on your organization’s devices, or leave the field out.

Authentication

401 with one of these messages:

• Missing or invalid Authorization header: send Authorization: Bearer <key>.
• Invalid API Key: the key is wrong or deleted, the Admin who created it is no longer an active member, or the organization no longer exists. See API keys.

Model errors

model_not_found

404. No model with that name exists. Check the spelling against your Models page, including the :Q4_K_M suffix.

model_disabled

403. The model exists but isn’t enabled for your organization: an Admin disabled or removed it, or never added it. Ask an Admin to enable it, or use another model.

model_unavailable

503, and you can retry. The model is enabled, but no device was ready to serve it:

• No device serving the model. Nodea waits up to 120 seconds for a device to become available, for example while one loads the model, and then returns this error. Check the Fleet page: are devices connected, and is any of them serving this model?
• Devices are serving it, but none supports a field you sent. The message names those devices. Update the app on them, or leave the field out.

Device errors

timeout

504, and you can retry. The device serving the request stopped responding. This happens when it produces no output for 180 seconds after the request starts, or goes 60 seconds between two pieces of output. Very long prompts on a busy device can hit the first limit.

node_error

502, and you can retry. The device reported an error, or disconnected before finishing (for example, it went to sleep or the app was quit).

Server errors

500, and you can retry. The server had an error while processing your request. If it keeps happening, contact hello@getnodea.com.

Errors during streaming

If an error happens before streaming starts, you get a normal HTTP error response.

If it happens after the first chunk has been sent, the HTTP status is already 200. Instead, the stream ends with a chunk that contains an error object in the format above, and no data: [DONE]. Treat a stream that ends without [DONE] as failed.

Retrying

For 500, 502, 503 and 504, retry with exponential backoff. The OpenAI SDKs do this for you, two retries by default. Don’t retry 4xx errors without changing the request or fixing the setup.