Error Codes

Detailed Description

Status codes returned by the library.

Functions
lcb_STATUS	lcb_errctx_kv_rc (const lcb_KEY_VALUE_ERROR_CONTEXT *ctx)
lcb_STATUS	lcb_errctx_kv_status_code (const lcb_KEY_VALUE_ERROR_CONTEXT *ctx, uint16_t *status_code)
lcb_STATUS	lcb_errctx_kv_opaque (const lcb_KEY_VALUE_ERROR_CONTEXT *ctx, uint32_t *opaque)
lcb_STATUS	lcb_errctx_kv_cas (const lcb_KEY_VALUE_ERROR_CONTEXT *ctx, uint64_t *cas)
lcb_STATUS	lcb_errctx_kv_key (const lcb_KEY_VALUE_ERROR_CONTEXT *ctx, const char **key, size_t *key_len)
lcb_STATUS	lcb_errctx_kv_bucket (const lcb_KEY_VALUE_ERROR_CONTEXT *ctx, const char **bucket, size_t *bucket_len)
lcb_STATUS	lcb_errctx_kv_collection (const lcb_KEY_VALUE_ERROR_CONTEXT *ctx, const char **collection, size_t *collection_len)
lcb_STATUS	lcb_errctx_kv_scope (const lcb_KEY_VALUE_ERROR_CONTEXT *ctx, const char **scope, size_t *scope_len)
lcb_STATUS	lcb_errctx_kv_context (const lcb_KEY_VALUE_ERROR_CONTEXT *ctx, const char **context, size_t *context_len)
lcb_STATUS	lcb_errctx_kv_ref (const lcb_KEY_VALUE_ERROR_CONTEXT *ctx, const char **ref, size_t *ref_len)
lcb_STATUS	lcb_errctx_kv_endpoint (const lcb_KEY_VALUE_ERROR_CONTEXT *ctx, const char **endpoint, size_t *endpoint_len)
lcb_STATUS	lcb_errctx_query_rc (const lcb_QUERY_ERROR_CONTEXT *ctx)
lcb_STATUS	lcb_errctx_query_first_error_code (const lcb_QUERY_ERROR_CONTEXT *ctx, uint32_t *code)
lcb_STATUS	lcb_errctx_query_first_error_message (const lcb_QUERY_ERROR_CONTEXT *ctx, const char **message, size_t *message_len)
lcb_STATUS	lcb_errctx_query_error_response_body (const lcb_QUERY_ERROR_CONTEXT *ctx, const char **body, size_t *body_len)
lcb_STATUS	lcb_errctx_query_statement (const lcb_QUERY_ERROR_CONTEXT *ctx, const char **statement, size_t *statement_len)
lcb_STATUS	lcb_errctx_query_client_context_id (const lcb_QUERY_ERROR_CONTEXT *ctx, const char **id, size_t *id_len)
lcb_STATUS	lcb_errctx_query_query_params (const lcb_QUERY_ERROR_CONTEXT *ctx, const char **params, size_t *params_len)
lcb_STATUS	lcb_errctx_query_http_response_code (const lcb_QUERY_ERROR_CONTEXT *ctx, uint32_t *code)
lcb_STATUS	lcb_errctx_query_http_response_body (const lcb_QUERY_ERROR_CONTEXT *ctx, const char **body, size_t *body_len)
lcb_STATUS	lcb_errctx_query_endpoint (const lcb_QUERY_ERROR_CONTEXT *ctx, const char **endpoint, size_t *endpoint_len)
lcb_STATUS	lcb_errctx_analytics_rc (const lcb_ANALYTICS_ERROR_CONTEXT *ctx)
lcb_STATUS	lcb_errctx_analytics_first_error_code (const lcb_ANALYTICS_ERROR_CONTEXT *ctx, uint32_t *code)
lcb_STATUS	lcb_errctx_analytics_first_error_message (const lcb_ANALYTICS_ERROR_CONTEXT *ctx, const char **message, size_t *message_len)
lcb_STATUS	lcb_errctx_analytics_statement (const lcb_ANALYTICS_ERROR_CONTEXT *ctx, const char **statement, size_t *statement_len)
lcb_STATUS	lcb_errctx_analytics_query_params (const lcb_ANALYTICS_ERROR_CONTEXT *ctx, const char **query_params, size_t *query_params_len)
lcb_STATUS	lcb_errctx_analytics_client_context_id (const lcb_ANALYTICS_ERROR_CONTEXT *ctx, const char **id, size_t *id_len)
lcb_STATUS	lcb_errctx_analytics_http_response_code (const lcb_ANALYTICS_ERROR_CONTEXT *ctx, uint32_t *code)
lcb_STATUS	lcb_errctx_analytics_http_response_body (const lcb_ANALYTICS_ERROR_CONTEXT *ctx, const char **body, size_t *body_len)
lcb_STATUS	lcb_errctx_analytics_endpoint (const lcb_ANALYTICS_ERROR_CONTEXT *ctx, const char **endpoint, size_t *endpoint_len)
lcb_STATUS	lcb_errctx_view_rc (const lcb_VIEW_ERROR_CONTEXT *ctx)
lcb_STATUS	lcb_errctx_view_first_error_code (const lcb_VIEW_ERROR_CONTEXT *ctx, const char **code, size_t *code_len)
lcb_STATUS	lcb_errctx_view_first_error_message (const lcb_VIEW_ERROR_CONTEXT *ctx, const char **message, size_t *message_len)
lcb_STATUS	lcb_errctx_view_design_document (const lcb_VIEW_ERROR_CONTEXT *ctx, const char **name, size_t *name_len)
lcb_STATUS	lcb_errctx_view_view (const lcb_VIEW_ERROR_CONTEXT *ctx, const char **name, size_t *name_len)
lcb_STATUS	lcb_errctx_view_query_params (const lcb_VIEW_ERROR_CONTEXT *ctx, const char **params, size_t *params_len)
lcb_STATUS	lcb_errctx_view_http_response_code (const lcb_VIEW_ERROR_CONTEXT *ctx, uint32_t *code)
lcb_STATUS	lcb_errctx_view_http_response_body (const lcb_VIEW_ERROR_CONTEXT *ctx, const char **body, size_t *body_len)
lcb_STATUS	lcb_errctx_view_endpoint (const lcb_VIEW_ERROR_CONTEXT *ctx, const char **endpoint, size_t *endpoint_len)
lcb_STATUS	lcb_errctx_search_rc (const lcb_SEARCH_ERROR_CONTEXT *ctx)
lcb_STATUS	lcb_errctx_search_error_message (const lcb_SEARCH_ERROR_CONTEXT *ctx, const char **message, size_t *message_len)
lcb_STATUS	lcb_errctx_search_index_name (const lcb_SEARCH_ERROR_CONTEXT *ctx, const char **name, size_t *name_len)
lcb_STATUS	lcb_errctx_search_query (const lcb_SEARCH_ERROR_CONTEXT *ctx, const char **query, size_t *query_len)
lcb_STATUS	lcb_errctx_search_params (const lcb_SEARCH_ERROR_CONTEXT *ctx, const char **params, size_t *params_len)
lcb_STATUS	lcb_errctx_search_http_response_code (const lcb_SEARCH_ERROR_CONTEXT *ctx, uint32_t *code)
lcb_STATUS	lcb_errctx_search_http_response_body (const lcb_SEARCH_ERROR_CONTEXT *ctx, const char **body, size_t *body_len)
lcb_STATUS	lcb_errctx_search_endpoint (const lcb_SEARCH_ERROR_CONTEXT *ctx, const char **endpoint, size_t *endpoint_len)
lcb_STATUS	lcb_errctx_http_rc (const lcb_HTTP_ERROR_CONTEXT *ctx)
lcb_STATUS	lcb_errctx_http_path (const lcb_HTTP_ERROR_CONTEXT *ctx, const char **path, size_t *path_len)
lcb_STATUS	lcb_errctx_http_response_code (const lcb_HTTP_ERROR_CONTEXT *ctx, uint32_t *code)
lcb_STATUS	lcb_errctx_http_response_body (const lcb_HTTP_ERROR_CONTEXT *ctx, const char **body, size_t *body_len)
lcb_STATUS	lcb_errctx_http_endpoint (const lcb_HTTP_ERROR_CONTEXT *ctx, const char **endpoint, size_t *endpoint_len)
uint32_t	lcb_error_flags (lcb_STATUS err)
	Get error categories for a specific code. More...
LCB_INTERNAL_API const char *	lcb_strerror_short (lcb_STATUS error)
	Get a shorter textual description of an error message. More...
LCB_INTERNAL_API const char *	lcb_strerror_long (lcb_STATUS error)
	Get a longer textual description of an error message.
lcb_STATUS	lcb_errmap_default (lcb_INSTANCE *instance, lcb_U16 code)
	This may be used in conjunction with the errmap callback if it wishes to fallback for default behavior for the given code. More...
lcb_errmap_callback	lcb_set_errmap_callback (lcb_INSTANCE *instance, lcb_errmap_callback)
int	lcb_retry_reason_allows_non_idempotent_retry (lcb_RETRY_REASON code)
int	lcb_retry_reason_is_always_retry (lcb_RETRY_REASON code)
int	lcb_retry_request_is_idempotent (lcb_RETRY_REQUEST *req)
int	lcb_retry_request_retry_attempts (lcb_RETRY_REQUEST *req)
void *	lcb_retry_request_operation_cookie (lcb_RETRY_REQUEST *req)
lcb_STATUS	lcb_retry_strategy (lcb_INSTANCE *instance, lcb_RETRY_STRATEGY strategy)
	Set the global retry strategy. More...

Macros
#define	LCB_XERROR(X)
#define	LCB_ERROR_IS_NETWORK(e)
	if the error is a result of a network condition
#define	LCB_ERROR_IS_SUBDOC(e)
#define	LCB_ERROR_IS_TRANSIENT(e)
#define	LCB_ERROR_IS_FATAL(e)
#define	LCB_ERROR_IS_INPUT(e)
#define	LCB_XRETRY_REASON(X)

Typedefs
typedef struct lcb_KEY_VALUE_ERROR_CONTEXT_	lcb_KEY_VALUE_ERROR_CONTEXT
typedef struct lcb_QUERY_ERROR_CONTEXT_	lcb_QUERY_ERROR_CONTEXT
typedef struct lcb_ANALYTICS_ERROR_CONTEXT_	lcb_ANALYTICS_ERROR_CONTEXT
typedef struct lcb_VIEW_ERROR_CONTEXT_	lcb_VIEW_ERROR_CONTEXT
typedef struct lcb_SEARCH_ERROR_CONTEXT_	lcb_SEARCH_ERROR_CONTEXT
typedef struct lcb_HTTP_ERROR_CONTEXT_	lcb_HTTP_ERROR_CONTEXT
typedef lcb_STATUS(*	lcb_errmap_callback) (lcb_INSTANCE *instance, lcb_U16 bincode)
	Callback for error mappings. More...
typedef struct lcb_RETRY_REQUEST_	lcb_RETRY_REQUEST
typedef lcb_RETRY_ACTION(*	lcb_RETRY_STRATEGY) (lcb_RETRY_REQUEST *req, lcb_RETRY_REASON reason)

Enumerations
enum	lcb_ERROR_TYPE
enum	lcb_ERROR_FLAGS
enum	lcb_STATUS
	Error codes returned by the library. More...
enum	lcb_RETRY_REASON

Function Documentation

lcb_error_flags()

uint32_t lcb_error_flags

(

lcb_STATUS

err

)

Get error categories for a specific code.

Parameters

err	the error received

Returns

a set of flags containing the categories for the given error

Stability

Committed:

lcb_strerror_short()

LCB_INTERNAL_API const char* lcb_strerror_short

(

lcb_STATUS

error

)

Get a shorter textual description of an error message.

This is the constant name

Examples

example/analytics/analytics.c, example/crypto/openssl_symmetric_decrypt.c, example/crypto/openssl_symmetric_encrypt.c, example/fts/fts.c, example/libeventdirect/main.c, example/minimal/minimal.c, example/minimal/query.c, example/subdoc/subdoc-xattrs.c, example/threads-private/threads-private.c, example/threads-shared/threads-shared.c, example/tracing/tracing.c, and example/tracing/views.c.

lcb_errmap_default()

lcb_STATUS lcb_errmap_default	(	lcb_INSTANCE *	instance,
		lcb_U16	code
	)

This may be used in conjunction with the errmap callback if it wishes to fallback for default behavior for the given code.

Stability

Uncommitted:

lcb_set_errmap_callback()

lcb_errmap_callback lcb_set_errmap_callback	(	lcb_INSTANCE *	instance,
		lcb_errmap_callback
	)

Stability

Uncommitted:

lcb_retry_strategy()

lcb_STATUS lcb_retry_strategy	(	lcb_INSTANCE *	instance,
		lcb_RETRY_STRATEGY	strategy
	)

Set the global retry strategy.

A strategy is a function pointer (see typedef above) which takes a lcb_RETRY_REQUEST and an lcb_RETRY_REASON, and returns a lcb_RETRY_ACTION. There are a number of lcb_retry_reason_*** and lcb_retry_request_*** functions one can use to formulate a stragegy. The simplest possible strategy:

lcb_RETRY_ACTION lcb_retry_strategy_fail_fast(lcb_RETRY_REQUEST *req, lcb_RETRY_REASON reason) {
   lcb_RETRY_ACTION res{0, 0};
   return res;
}

This sets should_retry to false for all requests. Below, we use the functions mentioned above to formulate a more nuanced strategy:

lcb_RETRY_ACTION lcb_retry_strategy_best_effort(lcb_RETRY_REQUEST *req, lcb_RETRY_REASON reason) {
    lcb_RETRY_ACTION res{0, 0};
    if (lcb_retry_request_is_idempotent(req) || lcb_retry_reason_allows_non_idempotent_retry(reason)) {
         res.should_retry = 1;
         res.retry_after_ms = 0;
    }
    return res;
}

These 2 strategies are pre-defined for you to use, or you can formulate your own.

Typedef Documentation

lcb_errmap_callback

typedef lcb_STATUS(* lcb_errmap_callback) (lcb_INSTANCE *instance, lcb_U16 bincode)

Callback for error mappings.

This will be invoked when requesting whether the user has a possible mapping for this error code.

This will be called for response codes which may be ambiguous in most use cases, or in cases where detailed response codes may be mapped to more generic ones.

Enumeration Type Documentation

lcb_STATUS

enum lcb_STATUS

Error codes returned by the library.

Enumerator
LCB_MAX_ERROR	The errors below this value reserved for libcouchbase usage.