Errors and limits

Status codes

Every error is reported with a gRPC status, or the matching HTTP status over REST. Error messages for client errors say exactly what was wrong; server-side errors carry a generic message.

gRPC	HTTP	Cause	What to do
INVALID_ARGUMENT	400	A request failed validation — a bad name, a limit exceeded, malformed points, a streaming protocol violation — or a workspace name is ambiguous without organization. Nothing from the request was applied.	Fix the request. Do not retry it unchanged.
UNAUTHENTICATED	401	Missing, malformed or expired access token.	Refresh the token and retry.
PERMISSION_DENIED	403	No member access to the workspace, or the workspace does not exist.	Check the workspace name and your role.
NOT_FOUND	404	The run, project (with createProjectIfMissing false) or fork parent does not exist.	Create it first, or fix the name.
ALREADY_EXISTS	409	CreateRun for a run that exists, or an InitializeRunLogging attach refused by the resume policy.	See Conflicts.
RESOURCE_EXHAUSTED	429	The request did not fit under the workspace’s or organization’s write rate within the server’s pacing delay. Metric logging and tracing have separate rates. Nothing from the request was accounted. The message names the limit.	Retry after a longer backoff and send less per second.
INTERNAL	500	An unexpected server error.	Retry with backoff.
UNAVAILABLE	503	The ingestion pipeline is overloaded and shedding load, a dependency is temporarily unavailable, the handshake timed out waiting for the pipeline, or the server is shutting down.	Retry with backoff.
CANCELLED	504	The request did not finish within the server’s timeout (15 seconds by default).	Retry with backoff; send smaller requests.

A 409 from CreateRun carries a JSON body with the existing run’s creation_time and orchestration_identifier. Every other REST error body is plain text.

Retrying

Retry with exponential backoff and jitter — for example, starting at 100 ms and doubling up to a few seconds. Writes are at-least-once and replays are harmless (see Retries and duplicates), so a request whose outcome is unknown can always be sent again.

Limits

These are enforced when a request is validated; exceeding one is INVALID_ARGUMENT. Lengths are in bytes of UTF-8.

Names

Item	Limit	Characters
Project, run name, fork parent	512 bytes	No whitespace or control characters; none of ( ) [ ] , = < > ! ~ " | or / \ ? # %; must not start with :; not a reserved portal route name.
Environment id	128 bytes	As project and run names.
Metric name	256 bytes	As above, but / is allowed.
Scale	64 bytes	As metric names. Empty means ML_STEP.
Attribute path	512 bytes	As metric names. sys/… is read-only except sys/description and sys/tags.
Label key	64 bytes	As metric names, and no &.
Label value	64 bytes	Anything except control characters, = and &.
Labels per series	8
Orchestration identifier	256 bytes	Any printable text.
Span or trace name	512 bytes	Not empty.

Values and points

Item	Limit
String attribute	16 KiB
String set attribute (or delta)	32 KiB across its values
Step, RL step, minor step, episode	0 to 2^63 − 1
Values per PointBatch or RlStepBatch	10,000
Histogram bin edges	2 to 513 (at most 512 bins), finite and strictly increasing
Histogram points per update	128
Scatter coordinates per step, and per update	32,768
Scatter points (steps) per update	128
Span payload body	16 MiB (longer bodies are truncated, not rejected)
Attributes per span payload	256
Span attribute value	64 KiB

Requests

Item	Limit
REST request body	2 MB
gRPC message	4 MiB
Request timeout	15 seconds (unary calls and the handshake)
Handshake wait for the pipeline	about 30 seconds, then UNAVAILABLE
Logger inactivity before a run is marked crashed	15 minutes

Timeouts and inactivity windows are defaults; a self-hosted deployment may configure them differently.