Errors and limits

Match the HTTP status and the response's error code. Additional fields describe the failure; validation responses can also include a detail list.

{ "error": "rate_limited", "retry_after_seconds": 21 }

Errors by status

Status	Common codes	Action
400	invalid_input, invalid_content_length, field_type_conflict, missing_link_ids, too_many_link_ids, unknown_query_parameter	Correct the named field or reduce the request.
401	auth_failed	Stop requests and correct the API key or environment.
403	insufficient_scope, tenant_disabled, live_ingest_not_entitled, plan_upgrade_required	Stop requests and resolve the missing scope or account access.
404	predictions_not_enabled	Confirm prediction serving is enabled in the deployment.
411	length_required	Send Content-Length with the request body.
413	request_too_large, batch_too_large	Split the payload before retrying.
422	validation_error, endpoint-specific validation codes	Correct the input. Inspect detail and the endpoint reference.
429	auth_lockout, rate_limited	Follow the distinct recovery steps below.
500	internal_error	Record the incident_id, if present, for support.
503	telemetry_unavailable, tenant_unavailable, prediction_store_unavailable, ingest_buffer_full, entitlement_unavailable	Respect the retry delay. Contact support if the failure persists.

Endpoint-specific errors are listed under Telemetry, Topology, and Predictions.

Failed-auth lockout

HTTP authentication lockout is separate from request rate limiting. The server defaults are:

Scope	Failure threshold	Lockout duration
Client IP and credential pair	5 failures within 300 seconds	300 seconds
Client IP	50 failures within 300 seconds	900 seconds

A locked IP-and-credential pair or client IP receives 429 auth_lockout. The pair lock affects that credential from that IP. An IP-wide lock also blocks a corrected key until it expires. Thresholds can vary by environment.

Stop the client producing authentication failures, fix its credential, and wait the full Retry-After delay. Clients sharing an outbound IP can be affected by the same IP lockout. Do not keep probing a rejected key.

Rate limits

The HTTP server defaults are:

Scope	Limit
Client IP	300 requests/minute
Authenticated account or tenant	300 requests/minute sustained
Authenticated account or tenant burst	20 requests/second

Limits can vary by environment. HTTP middleware limits and lockouts are separate from gRPC ingest handling. /health and /health/* are exempt. Other unauthenticated requests and failed authentication attempts consume the client-IP budget.

Exceeding a traffic limit returns 429 rate_limited. Pause requests that share the affected budget and honor Retry-After. Batch requests and reduce polling frequency if the limit recurs.

Body limits

HTTP limit	Maximum
Request body	1 MiB (1,048,576 bytes)
Telemetry batch	1,000 records

Both limits apply; split by encoded body size as well as record count. Body-carrying requests require Content-Length. The gRPC telemetry contract has its own batch limits.

Retry guidance

Result	Client behavior
401 or 403	Stop automated requests. Correct the credential, scope, or access configuration before resuming.
429 auth_lockout	Stop the failing client, fix authentication, and wait the full retry delay.
429 rate_limited	Wait the full retry delay and reduce the request rate if it recurs.
503 or a failed read	Use bounded exponential backoff with jitter. Honor a server-provided retry delay.
Other 4xx	Correct the request before retrying; reconcile any store-side partial write.
Ambiguous telemetry write	Reconcile the batch before replaying it.

Retry-After can be a number of seconds or an HTTP date. If it is absent, use a valid retry_after_seconds response field; otherwise use bounded exponential backoff. Add jitter after the required wait, and never shorten a server-provided delay with a local backoff cap.

Telemetry writes have no request idempotency key. If a connection drops or a write times out after submission, the batch may already have been accepted. Check delivery before replaying it. On partial acceptance, inspect the rejection details and resend only corrected rejected records. See Telemetry.