Conventional HTTP response codes are returned to indicate the success or failure of an API request.
Some codes are retryable, meaning that simply re-issuing the same request after experiencing this code could lead to a successful result.
Retrying a request could lead to duplication of records, unless the code from the prior attempt is guarantees that the attempt had no side effects.
This is only relevant for append operations, and SDKs allow users to specify whether or not retryable codes that may have had a side effect should ever be retried.
All errors return a JSON object with the following structure:
{
"code": "error_code",
"message": "A human-readable description of the error"
}
| Field | Type | Description |
|---|
code | string | A short string identifying the error type. |
message | string | A message providing more details about the error. |
Error Codes
Request Errors
| Code | HTTP Status | Description |
|---|
bad_json | 400 | The request body contains invalid JSON or failed to deserialize into the expected type. Check the error message for details. |
bad_proto | 400 | The request body contains invalid Protocol Buffers data. Ensure the protobuf message is correctly encoded. |
bad_path | 400 | One or more path parameters are invalid or malformed. Check that resource names in the URL path conform to naming requirements. |
bad_query | 400 | One or more query string parameters are invalid or malformed. Verify that query parameters have valid values and types. |
bad_bytes | 400 | The request body byte stream is invalid. Ensure the request body is properly encoded. |
bad_content_type | 400 | The Content-Type header is missing or invalid. Include a valid Content-Type header (e.g., application/json) with your request. |
bad_s2_format | 400 | The S2-Format header value is invalid. Use a supported format value (raw or base64). |
bad_body | 400 | The request body structure is invalid or cannot be decoded. Verify the request body matches the expected schema. |
bad_idempotence_key | 400 | The idempotence key (s2-request-token header) is invalid. The key must be ASCII characters only and cannot exceed 36 characters. |
bad_params | 400 | One or more request parameters failed validation. Check the error message for details about which parameter is invalid. |
bad_config | 400 | The basin or stream configuration update is invalid. Verify the configuration changes are valid and compatible with the current state. |
invalid | 400 | A field value failed type validation. Ensure all fields conform to their expected types and constraints (e.g., name length limits, character restrictions). |
validation | 400 | The metrics request failed validation. Check that the requested time range and parameters are valid. |
These errors are not retryable, as they reflect issues with the request itself. Fix the request before retrying. No side effects occur.
Authentication and Authorization Errors
| Code | HTTP Status | Description |
|---|
authn | 401 | Authentication failed. The access token is missing, invalid, or expired. Provide a valid access token in the Authorization header. |
permission_denied | 403 | The authenticated token does not have permission to perform this operation. Verify the token has the required scope and permissions for the requested resource and operation. |
These errors are not retryable without fixing the authentication or permissions. No side effects occur.
Basin Errors
| Code | HTTP Status | Description |
|---|
basin_not_found | 404 | The specified basin does not exist. Verify the basin name is correct and that the basin has been created. |
basin_exists | 409 | A basin with this name already exists. Choose a different basin name or use the existing basin. |
basin_creating | 503 | The basin is currently being provisioned and is not yet available. |
basin_scope_mismatch | 400 | The requested scope does not match the existing basin configuration. Ensure the scope in your request matches the basin’s configured scope. |
basins_limit | 403 | The account has reached its maximum number of basins. Delete unused basins or contact support to increase your limit. |
invalid_basin_config | 400 | The basin configuration is invalid. Check that all configuration values are within allowed ranges and constraints. |
basin_deleted | 409 | The basin was deleted while a reconfiguration was in progress. The operation cannot be completed. |
too_many_basin_creations | 429 | Too many basin creation requests are being processed concurrently. |
basin_creating and too_many_basin_creations are retryable after a delay. Other errors are not retryable without changing the request. No side effects occur.
Stream Errors
| Code | HTTP Status | Description |
|---|
stream_not_found | 404 | The specified stream does not exist. Verify the stream name is correct and that the stream has been created in the basin. |
stream_exists | 409 | A stream with this name already exists in the basin. Choose a different stream name or use the existing stream. |
stream_being_deleted | 409 | The stream is currently being deleted. Wait for the deletion to complete before creating a new stream with the same name. |
invalid_stream_config | 400 | The stream configuration is invalid. Check that all configuration values are within allowed ranges and constraints for your account tier. |
stream_deleted_during_reconfiguration | 409 | The stream was deleted while a reconfiguration was in progress. The operation cannot be completed. |
concurrent_stream_update | 409 | Another update to this stream is currently in progress. |
These errors are not retryable without changing the request or waiting for the conflicting operation to complete. No side effects occur.
Access Token Errors
| Code | HTTP Status | Description |
|---|
token_exists | 409 | An access token with this ID already exists. Choose a different token ID. |
token_not_found | 404 | The specified access token does not exist. Verify the token ID is correct. |
These errors are not retryable without changing the request. No side effects occur.
Record Operation Errors
| Code | HTTP Status | Description |
|---|
ack_timeout | 408 | The append operation timed out waiting for acknowledgment. The records may or may not have been written. |
channel_timeout | 408 | The request timed out while communicating with the backend. |
channel_unavailable | 503 | The backend service is temporarily unavailable. |
channel_overload | 503 | The backend service is experiencing high load. |
hot_server | 502 | The server is temporarily rejecting requests due to high load. |
download | 503 | The server is temporarily rejecting requests. |
rate_limited | 429 | The append rate limit for this stream has been exceeded. Reduce the request rate or contact support to increase your limits. |
All of these errors are retryable. However, for append operations, all errors except hot_server (502) may have caused a side effect.
Metrics Errors
| Code | HTTP Status | Description |
|---|
metrics_unavailable | 503 | The metrics service is temporarily unavailable. |
This error is retryable after a delay. No side effects occur (read-only operation).
Internal Errors
| Code | HTTP Status | Description |
|---|
internal | 500 | An unexpected internal error occurred. If this error persists, contact support. |
This error is retryable, but the operation may have caused a side effect.
Tail Exceeded (416 Range Not Satisfiable)
Returned when a read operation requests a starting position beyond the current tail of the stream.
The tail field indicates the current end position of the stream. Adjust your read request to start at or before this position, or use this value to wait for new records.
Append Condition Failed (412 Precondition Failed)
Returned when a conditional append fails due to a fencing token or sequence number mismatch.
Fencing Token Mismatch
Sequence Number Mismatch
{
"fencing_token_mismatch": "expected_token_value"
}
{
"seq_num_mismatch": 12345
}
match_seq_num is set. 
