onelifevibe

Platform API error

invalid_topic

invalid_topic is a 400 error returned when a subscription or ingest topic isn't valid. Fix the topic name and retry.

Updated November 6, 2026

HTTP status
400
Code
invalid_topic
API
Platform API v1

Returned when

What to do

Example answer

HTTP/1.1 400
content-type: application/json

{
  "error": {
    "code": "invalid_topic",
    "message": "Unknown topic <topic>."
  }
}

Related errors

What it means

The Platform API rejected your request because a topic value is not valid. The response carries HTTP 400 and an error body in this shape: {"error":{"code":"…","message":"…","hint":"…"}}. The code field is invalid_topic.

Topics show up in two places: subscriptions and ingest. A subscription topic has to name a real event type or a namespace wildcard that covers one. An ingest topic has to look like order.placed. A bad value in either place produces invalid_topic.

Codes are stable, so match on code rather than on the message text. The message may read Unknown topic <topic>. or topic must look like "order.placed"., but the code is what you should branch on.

Why you are seeing it

For subscriptions, the topic is either not a real event type or not a wildcard that covers one. The event types are tool.invoked, client.approved, client.suspended, subscription.changed and world.event. The wildcards are tool.*, client.*, world.* and *.

That means a misspelled or invented name fails, and so does a wildcard that matches nothing. Something like tool.invoke or client.aproved will come back as invalid_topic instead of being accepted quietly.

For ingest, the topic does not have the shape the API expects: lowercase words separated by dots, such as order.placed. A space, an uppercase letter, a single word with no dot, or a stray character is enough to trigger it.

How to fix it

For a subscription, pick an event type from the docs exactly as written, or use a wildcard that matches at least one of them. Check spelling character by character, since tool.invoked and subscription.changed are easy to mistype.

For ingest, send two to four dot-separated parts with lowercase words, such as order.placed. Send the topic value you intend, not a display label or a free-text description of the event.

If you generate topics from configuration or user input, validate them before the call. One clean request after the fix is usually all it takes.

Handling it in code

Parse the error body and check that error.code equals invalid_topic. Treat it as a client-side problem with the request you built, not something a blind retry will cure. Retrying the same topic just returns the same 400.

Log the topic value alongside the message so the failing string is obvious in your logs. For ingest, validate the shape before sending: dot-separated, lowercase, two to four parts. For subscriptions, compare against the documented event types and wildcards.

Check the related errors invalid_world and invalid_data if the same request also carries a world or payload. When several fields are wrong at once, fix the topic first, then resend.

Questions

What HTTP status does invalid_topic return?

HTTP 400. The body follows the standard error shape with code, message and hint fields.

Which subscription topics are valid?

The event types tool.invoked, client.approved, client.suspended, subscription.changed and world.event, plus the wildcards tool.*, client.*, world.* and *.

What should an ingest topic look like?

Two to four dot-separated lowercase parts, such as order.placed. If it does not look like that, the API returns invalid_topic.

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.