Skip to content

Error handling

Every error raised by the SDK is a DatadogLogsError (Java: DatadogLogsException, Go: *Error, Rust: Error) with the same fields in every language:

Field Meaning
code one of the codes below
message "<operation>: <short reason> (HTTP <status>)" — never contains secrets, tokens, request bodies or unfiltered response bodies
httpStatus HTTP status, when the error came from a response
requestId vendor request id header, when present
retryable whether retrying the same call may succeed
retryAfter server-requested wait (RATE_LIMITED, UNAVAILABLE), when known
cause underlying error (redacted)

Vendor error text from a response body is redacted and truncated to 300 characters.

Error codes

Code TypeScript / Python Rust Go Java Typical source Retryable
CONFIG ConfigError Error::Config ErrConfig ConfigException invalid or missing configuration no
AUTHENTICATION AuthenticationError Error::Authentication ErrAuthentication AuthenticationException HTTP 401 no
PERMISSION_DENIED PermissionDeniedError Error::PermissionDenied ErrPermissionDenied PermissionDeniedException HTTP 403 no
NOT_FOUND NotFoundError Error::NotFound ErrNotFound NotFoundException HTTP 404, missing record no
CONFLICT ConflictError Error::Conflict ErrConflict ConflictException HTTP 409, 412, CAS mismatch no
RATE_LIMITED RateLimitError Error::RateLimited ErrRateLimited RateLimitException HTTP 429 yes
VALIDATION ValidationError Error::Validation ErrValidation ValidationException HTTP 400, 413, 422, other 4xx, bad input no
UNAVAILABLE UnavailableError Error::Unavailable ErrUnavailable UnavailableException network error, HTTP 500, 502, 503 yes
TIMEOUT TimeoutError Error::Timeout ErrTimeout TimeoutException deadline exceeded, HTTP 408, 504 yes
UNSUPPORTED UnsupportedError Error::Unsupported ErrUnsupported UnsupportedException capability the service or deployment does not offer, HTTP 501 no
CANCELLED CancelledError Error::Cancelled ErrCancelled CancelledException the caller cancelled no

The client already retries retryable errors (see Configuration); an error you receive means the retries are exhausted or the error is not retryable.

Handling errors

import { NotFoundError, RateLimitError, DatadogLogsError } from "@grow-codes/datadog-logs";

try {
  await client.ping();
} catch (err) {
  if (err instanceof RateLimitError) {
    console.warn("rate limited, retry after", err.retryAfterMs, "ms");
  } else if (err instanceof NotFoundError) {
    // handle missing resource
  } else if (err instanceof DatadogLogsError) {
    console.error(err.code, err.httpStatus, err.requestId, err.retryable, err.message);
  } else {
    throw err;
  }
}
use grow_datadog_logs::{Error, ErrorCode};

match client.ping().await {
    Ok(latency) => println!("{latency:?}"),
    Err(err) if err.code() == ErrorCode::RateLimited => {
        eprintln!("rate limited, retry after {:?}", err.retry_after());
    }
    Err(Error::NotFound(_)) => { /* handle missing resource */ }
    Err(err) => eprintln!(
        "{:?} {:?} {:?} retryable={} {err}",
        err.code(), err.http_status(), err.request_id(), err.is_retryable()
    ),
}
_, err := client.Ping(ctx)
switch {
case err == nil:
case errors.Is(err, datadoglogs.ErrRateLimited):
    var e *datadoglogs.Error
    errors.As(err, &e)
    log.Printf("rate limited, retry after %s", e.RetryAfter)
case errors.Is(err, datadoglogs.ErrNotFound):
    // handle missing resource
case errors.Is(err, context.Canceled): // also errors.Is(err, datadoglogs.ErrCancelled)
    return err
default:
    var e *datadoglogs.Error
    if errors.As(err, &e) {
        log.Printf("%s status=%d request=%s retryable=%t: %s", e.Code, e.HTTPStatus, e.RequestID, e.Retryable, e.Message)
    }
}
from grow_datadog_logs import NotFoundError, RateLimitError, DatadogLogsError

try:
    client.ping()
except RateLimitError as err:
    print("rate limited, retry after", err.retry_after, "s")
except NotFoundError:
    ...  # handle missing resource
except DatadogLogsError as err:
    print(err.code, err.http_status, err.request_id, err.retryable, err)

TimeoutError here is the SDK class (grow_datadog_logs.TimeoutError), not the built-in.

import codes.grow.packages.datadoglogs.core.NotFoundException;
import codes.grow.packages.datadoglogs.core.RateLimitException;
import codes.grow.packages.datadoglogs.core.DatadogLogsException;

try {
  client.ping();
} catch (RateLimitException e) {
  System.err.println("rate limited, retry after " + e.retryAfter());
} catch (NotFoundException e) {
  // handle missing resource
} catch (DatadogLogsException e) {
  System.err.println(e.code() + " " + e.httpStatus() + " " + e.requestId() + " " + e.retryable());
}

The exceptions are unchecked. TimeoutException lives in the SDK package and is not java.util.concurrent.TimeoutException. Async variants complete exceptionally with the same exceptions (wrapped in CompletionException).

Retrying yourself

Retry only when retryable is true, wait at least retryAfter when it is set, and keep an overall deadline. Never retry VALIDATION, AUTHENTICATION or PERMISSION_DENIED without changing the request or the credentials.