Platform API error

invalid_json

invalid_json (HTTP 400) means the Platform API could not use your request body because it is not a JSON object.

Updated November 6, 2026

HTTP status: 400
Code: invalid_json
API: Platform API v1

Returned when

The body is not valid JSON.
The body parsed, but it is an array, a string or null instead of an object.

What to do

Send Content-Type: application/json and a JSON object, for example {"arguments":{}} for a tool call.
Build the body with a JSON serializer instead of string concatenation.

Example answer

HTTP/1.1 400
content-type: application/json

{
  "error": {
    "code": "invalid_json",
    "message": "The body is not valid JSON."
  }
}

Related errors

invalid_arguments The tool's arguments do not match its input schema.
payload_too_large The request body is too big.

What it means

The Platform API returns invalid_json with HTTP status 400 when the request body is not a JSON object. The body either failed to parse as JSON at all, or it parsed into something that is not an object: an array, a string or null.

Every error response uses the same shape: an error object containing code, message and hint. The code field is stable, so match on invalid_json in your error handling. The message text can change, and it arrives in one of two forms: "The body is not valid JSON." or "The body must be a JSON object." Do not branch on either string.

The check happens before your request does any work, so nothing is read, written or charged on a body that fails it. Fixing the body and resending is the whole recovery path.

Why you are seeing it

The most common cause is malformed JSON: a trailing comma, single quotes around keys, an unquoted key, a value cut short, or two objects concatenated. A body built by string concatenation tends to produce exactly this.

A second cause looks correct but is the wrong type. The body parses cleanly, yet the top-level value is an array, a string or null rather than an object. Sending [{"arguments":{}}] or a bare "text" string returns invalid_json even though the syntax is fine.

An empty body, or one sent without Content-Type: application/json, also lands here. Some HTTP clients set a form content type by default; check what your client actually puts on the wire before you look anywhere else.

How to fix it

Send Content-Type: application/json and a JSON object as the body. For a tool call, a minimal valid body is {"arguments":{}}. Even when a tool takes no inputs, send the object with an empty arguments value rather than nothing at all.

Build the body with a JSON serializer from your language or HTTP library instead of assembling it by hand. Serializing a map or dictionary guarantees quoting, escaping and commas are right, and it keeps the top-level value an object. If you must log the raw payload, log it before serialization so you can compare what you intended with what went out.

Validate before you send. Parse your own payload once in a test and confirm the top level is an object. Strip whitespace-only bodies and reject null early in your client code, so the request never leaves your side.

Handling it in code

Treat invalid_json as a client error and do not retry it unchanged. The same body will fail the same way. Retry only after you have built a new body. Backoff and repetition add load without changing the outcome.

Branch on the code field, not the message. A check like error.code == "invalid_json" stays correct across message changes. Read hint for a short pointer to the fix, and log code, message and hint together with the request you sent so the failing payload is easy to reproduce.

Keep the body in your logs with any sensitive values removed, and add a unit test that posts a known-bad body to confirm your handler catches invalid_json. When the request succeeds, the response is no longer an error object, so unwrap accordingly. If the body is an object but still wrong, check invalid_arguments; if it is large, check payload_too_large.

Questions

What HTTP status does invalid_json return?

invalid_json returns HTTP 400. It is sent when the body is not valid JSON, or when it parses but is an array, a string or null instead of an object.

Should I retry a request that returned invalid_json?

No. The same body will fail again, so retrying unchanged only adds requests. Rebuild the body as a JSON object and send it once more.

Which related error codes should I handle?

Handle invalid_arguments when the body is a valid object but the fields are wrong, and payload_too_large when the body exceeds the size limit. Match on the code value in every case, never on the message text.

Keys, plans and usage live in the console: rotate keys, add webhook endpoints, see the last 30 days.

Open the console Plans

Written from the OneLifeVibe tool registry and platform configuration, and checked automatically before publishing. Something wrong? Tell us.