Table of Contents

Class DatabentoApiException

Namespace
DatabentoDotNet.Historical
Assembly
DatabentoDotNet.Historical.dll

The Databento API rejected a request: the HTTP response carried a non-success status code.

public sealed class DatabentoApiException : Exception, ISerializable
Inheritance
DatabentoApiException
Implements
Inherited Members

Remarks

Port of upstream's ApiError (error.rs:63-79) and its Display (error.rs:104-125). Upstream wraps this as one arm, Error::Api, of a single enum spanning live, historical, and reference errors; PORTING.md §2 splits that enum by module instead, so a caller of the historical client is never in a position to catch a live-gateway exception it could not possibly have raised. This type is named DatabentoApiException rather than ApiException for the same reason DatabentoAuthenticationException in DatabentoDotNet.Live is — the type name itself is exempt from the repo's DatabentoDotNet.*-not-Databento.* naming rule, which is about packages, assemblies, and namespaces (CLAUDE.md, "Naming").

Constructors

DatabentoApiException()

Creates the exception with no message.

public DatabentoApiException()

DatabentoApiException(HttpStatusCode, string?, string?, string, string?, IReadOnlyDictionary<string, JsonElement>?)

Creates the exception from the parts of an API error response.

public DatabentoApiException(HttpStatusCode statusCode, string? requestId, string? errorCase, string message, string? docsUrl, IReadOnlyDictionary<string, JsonElement>? payload)

Parameters

statusCode HttpStatusCode

The HTTP status code of the response.

requestId string

The request-id response header, or null when the response carried none.

errorCase string

A machine-readable identifier for the error case, when the server returns a structured error envelope, or null for an unstructured error.

message string

The message from the Databento API.

docsUrl string

The link to documentation related to the error, or null when the server provides none.

payload IReadOnlyDictionary<string, JsonElement>

Additional context for the error, when the server provides one — common keys include dataset, start, end, available_start, and available_end — or null when it does not. Each element is cloned; see Payload.

Remarks

Message is composed the way upstream's Display composes it (error.rs:104-125), in the same order and from the same parts — nothing this library owns is interpolated into it, only what the response itself carried: "{requestId} failed with {status} {message}{docs}{case}" when there is a request id, and "{status} {message}{docs}{case}" when there is not, where status is "{(int)statusCode} {statusCode}" — both the number and the name, for the reason below — docs is " See {docsUrl} for documentation." or empty, and case is " (case: {errorCase})" or empty.

The statusCode segment renders differently from upstream's, and that is a documented departure, not an oversight. Upstream's reqwest::StatusCode has a canonical-reason-phrase table and its Display uses it — 400 Bad Request. HttpStatusCode carries no such table, and pulling one in from elsewhere (for example ASP.NET Core's ReasonPhrases) to reproduce the exact upstream text would add a dependency to a shipping HTTP client library for the sake of one string. But the BCL's own default rendering is not a clean fallback either, and not merely because it drops the number: it is not even consistent about it. HttpStatusCode.BadRequest.ToString() is "BadRequest" — a name, no number — while ((HttpStatusCode)498).ToString() is "498" — a number, no name, because 498 has no enum member. A caller grepping logs or filing a support ticket keys on the number, so this renders both explicitly — {(int)statusCode} {statusCode}, e.g. 400 BadRequest or 498 498 for a code neither the BCL nor this port names — rather than trusting either half to ToString() alone.

DatabentoApiException(string)

Creates the exception with a message.

public DatabentoApiException(string message)

Parameters

message string

The message.

DatabentoApiException(string, Exception)

Creates the exception with a message and an underlying cause.

public DatabentoApiException(string message, Exception innerException)

Parameters

message string

The message.

innerException Exception

The underlying cause.

Properties

Case

A machine-readable identifier for the error case, when the server returns a structured error envelope, or null for an unstructured error.

public string? Case { get; }

Property Value

string

DocsUrl

The link to documentation related to the error, or null when the server provides none.

public string? DocsUrl { get; }

Property Value

string

Payload

Additional context for the error, when the server provides one — common keys include dataset, start, end, available_start, and available_end. null when the server sent none; never an empty dictionary standing in for absent, because upstream's Option<Box<HashMap<..>>> distinguishes the two and this port does too.

public IReadOnlyDictionary<string, JsonElement>? Payload { get; }

Property Value

IReadOnlyDictionary<string, JsonElement>

Remarks

Every element is Clone()d at construction, deliberately. An un-cloned JsonElement points into the buffer owned by the JsonDocument that produced it, and that document is disposed as soon as the response finishes being read — so a property that held the elements as handed in would hand the caller a use-after-dispose the moment they read it after the fact, not a compile error the type system could ever catch. Cloning here makes the dictionary own its own memory and outlive the document that produced it.

RequestId

The request-id response header, or null when the response carried none.

public string? RequestId { get; }

Property Value

string

Remarks

This is what support asks for first when a request needs investigating (ROADMAP.md §5) — surfacing it as its own property, rather than leaving it buried in Message, is what lets a caller log or report it without parsing prose.

StatusCode

The HTTP status code of the response.

public HttpStatusCode StatusCode { get; }

Property Value

HttpStatusCode

Remarks

Through the three standard constructors, this is 0 — a value HttpStatusCode has no named member for, not a real status a server ever sends. Only the response constructor below sets a meaningful one; a caller that catches an exception built with a standard constructor should not branch on this property.

Edit this page