Errors

Every public codec member throws a CodecException. No NullReferenceException, InvalidCastException, KeyNotFoundException or JsonException escapes the boundary.

Exception	When	Carries
CodecUsageException	the API was used wrongly (null CloudEvent)	message
UnknownCodecException	no decoder/encoder for (contentType, T); null/empty content type on encode	ContentType, PayloadType, EventId
PayloadTypeMismatchException	a decoder returned something that is not T (including null)	expected and actual type
PayloadDecodeException	the decoder threw, or the data is not binary	InnerException preserved
PayloadEncodeException	the encoder threw, returned null, or wrote another content type; null payload	InnerException preserved
CodecRegistrationException	duplicate (contentType, T), null delegate, empty content type	content type and payload type

What a worker does with them

A worker maps a CodecException to its .error event, with the content type, payload type and event id in the message. A decoder's own exception is never hidden: it is InnerException.

Example

try
{
    var candle = codec.Decode<Candle>(cloudEvent);
}
catch (UnknownCodecException ex) when (ex.ContentType == "application/json")
{
    // a payload this worker does not read: skip, do not error
}
catch (PayloadDecodeException ex)
{
    // malformed payload: report ex.InnerException in the error event
}