Zerobus Ingest Error Handling

Error Handling

This section describes how errors are returned by the Zerobus Ingest API and how clients should handle them.

Error Response Format

REST (JSON)

Error responses are returned as JSON with an appropriate HTTP status code:

{
  "error_code": "NOT_FOUND",
  "message": "Table \"catalog.schema.table\" cannot be found."
}

Field	Type	Description
error_code	string	A machine-readable error code identifying the category of failure. Use this to determine how to handle the error programmatically.
message	string	A human-readable description of the error. May include additional diagnostic information for troubleshooting. Do not parse this field programmatically — its format may change without notice.

gPRC

Error responses use standard gRPC status codes, delivered via response trailers:

Trailer	Description
grpc-status	A numeric status code (e.g., 3 for INVALID_ARGUMENT). Use this to determine how to handle the error programmatically.
grpc-message	A human-readable description of the error. May include additional diagnostic information for troubleshooting. Do not parse this field programmatically — its format may change without notice.

Error Codes

The following table lists all error codes returned by the Zerobus Ingest API, their corresponding protocol-level codes, and recommended client behavior.

Client Errors

These errors indicate a problem with the request. Do not retry without modifying the request.

Error Code (REST)	gRPC Code	HTTP Status	Description	Recommended Action
INVALID_PARAMETER_VALUE	INVALID_ARGUMENT(3)	400	The request contains invalid or malformed input, such as a missing required field, an invalid schema, or an unsupported record format.	Fix the request and resubmit. Inspect the message field for details on which parameter is invalid.
NOT_FOUND	NOT_FOUND(5)	404	The requested resource does not exist. For example, the specified table cannot be found.	Verify that the resource name is correct and that it exists.
NOT_IMPLEMENTED	UNIMPLEMENTED(12)	501	The requested operation is not supported. For example, the table uses an unsupported feature or data format.	Do not retry. Check the message field for details on what is unsupported.

Authentication and Authorization Errors

These errors indicate issues with the caller's identity or permissions. Do not retry with the same credentials.

Error Code (REST)	gRPC Code	HTTP Status	Description	Recommended Action
UNAUTHENTICATED	UNAUTHENTICATED(16)	401	The request does not have valid authentication credentials. The token may be missing, empty, expired, or invalid.	Refresh or provide a valid authentication token and retry.
PERMISSION_DENIED	PERMISSION_DENIED(7)	403	The caller does not have sufficient privileges to perform the requested operation on the specified resource.	Verify that the caller has the required privileges (e.g., MODIFY, SELECT, USE_CATALOG, USE_SCHEMA) on the target resource.

Server Errors

These errors indicate a problem on the server side. Retry with exponential backoff and jitter.

Error Code (REST)	gRPC Code	HTTP Status	Description
UNAVAILABLE	UNAVAILABLE(14)	503	The service is temporarily unable to handle the request. This is typically a transient condition. Retry with exponential backoff and jitter.
RESOURCE_EXHAUSTED	RESOURCE_EXHAUSTED(8)	429	The service is rejecting requests due to resource limits. Reduce request concurrency if possible. Retry with exponential backoff and jitter.
INTERNAL_ERROR	INTERNAL_ERROR(13)	500	An unexpected internal error occurred. Do not retry. Contact support and provide the full error response for diagnosis.