Systemplane error list

Look up the error tokens the Systemplane admin API returns, the HTTP status each one carries, and what to do about it.

Error format

Most applications return Systemplane errors as a flat JSON object with the application/json media type:

JSON

{
  "code": 404,
  "title": "not_found",
  "message": "key not found"
}

The code field holds the HTTP status as a number. The machine-readable token is in title. Branch on title, not on code.

TED JD and JD Courier return these errors in their own error format.

Field definitions

• code – The HTTP status code, as an integer. It repeats the status of the response.
• title – A short machine-readable token for the error class. Use this value for programmatic handling.
• message – A human-readable description of what went wrong.

Client errors

---

title	Description	Status
bad_request	The request body is absent, unreadable, or holds no usable value field.	400
unknown_key	The key is not registered in the catalog.	400
validation_error	The value fails the validator for the key, or the namespace or key exceeds the maximum length.	400
not_supported	The operation is not available in this deployment.	400
tenant_connection_missing	The tenant database is absent from the request context.	400
nil_context	The request context is not available.	400
forbidden	The authorizer refused the action for this identity and namespace.	403
not_found	The requested key or catalog entry does not exist.	404

Authentication runs in the application that hosts the admin surface, ahead of the configuration routes. A request that fails authentication receives a 401 from that host application, in its own error format. Refer to the API reference of the application whose configuration you manage.

Server errors

---

title	Description	Status
internal_error	The request failed inside the service. The message stays generic. Retry, then contact support if the failure continues.	500
service_unavailable	The configuration store is not started, or it has stopped. Retry after a short interval.	503