Error handling¶
Every error raised by the SDK is a DatadogApmError (Java: DatadogApmException, 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, DatadogApmError } from "@grow-codes/datadog-apm";
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 DatadogApmError) {
console.error(err.code, err.httpStatus, err.requestId, err.retryable, err.message);
} else {
throw err;
}
}
use grow_datadog_apm::{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, datadogapm.ErrRateLimited):
var e *datadogapm.Error
errors.As(err, &e)
log.Printf("rate limited, retry after %s", e.RetryAfter)
case errors.Is(err, datadogapm.ErrNotFound):
// handle missing resource
case errors.Is(err, context.Canceled): // also errors.Is(err, datadogapm.ErrCancelled)
return err
default:
var e *datadogapm.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_apm import NotFoundError, RateLimitError, DatadogApmError
try:
client.ping()
except RateLimitError as err:
print("rate limited, retry after", err.retry_after, "s")
except NotFoundError:
... # handle missing resource
except DatadogApmError as err:
print(err.code, err.http_status, err.request_id, err.retryable, err)
TimeoutError here is the SDK class (grow_datadog_apm.TimeoutError), not the built-in.
import codes.grow.packages.datadogapm.core.NotFoundException;
import codes.grow.packages.datadogapm.core.RateLimitException;
import codes.grow.packages.datadogapm.core.DatadogApmException;
try {
client.ping();
} catch (RateLimitException e) {
System.err.println("rate limited, retry after " + e.retryAfter());
} catch (NotFoundException e) {
// handle missing resource
} catch (DatadogApmException 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.