specs/openapi.yaml defines ErrorResponse with required: [type, title, status, code, message], and the shared BadRequest / Unauthorized / Forbidden / TooManyRequests / ServiceUnavailable / InternalServerError responses all reference it. Every path in the spec uses those shared responses.
No handler emits that shape. Routes return { error, code } — sometimes { error } alone, sometimes with extra fields such as retryable or requestId. A typed client generated from the spec therefore cannot deserialize any documented failure from any endpoint.
This surfaced in review of #75 as a comment on the new sponsor-proof route, but that route follows the same convention as every other handler in the repo, so fixing it alone would make it the one endpoint that differs. Leaving it out of that PR deliberately.
Two coherent ways to close it, and the choice is a product decision rather than a cleanup:
- Make the handlers match the spec. Emit
type, title, status, code, message everywhere, via one error helper. This is a breaking change for anyone parsing error today, so it wants a version bump and a note in the SDKs.
- Make the spec match the handlers. Redefine
ErrorResponse as { error, code, ... }. Non-breaking, but it gives up the RFC 7807-shaped contract the schema was reaching for.
Worth deciding before the SDKs grow more error-handling code against the current de-facto shape.
specs/openapi.yamldefinesErrorResponsewithrequired: [type, title, status, code, message], and the sharedBadRequest/Unauthorized/Forbidden/TooManyRequests/ServiceUnavailable/InternalServerErrorresponses all reference it. Every path in the spec uses those shared responses.No handler emits that shape. Routes return
{ error, code }— sometimes{ error }alone, sometimes with extra fields such asretryableorrequestId. A typed client generated from the spec therefore cannot deserialize any documented failure from any endpoint.This surfaced in review of #75 as a comment on the new sponsor-proof route, but that route follows the same convention as every other handler in the repo, so fixing it alone would make it the one endpoint that differs. Leaving it out of that PR deliberately.
Two coherent ways to close it, and the choice is a product decision rather than a cleanup:
type,title,status,code,messageeverywhere, via one error helper. This is a breaking change for anyone parsingerrortoday, so it wants a version bump and a note in the SDKs.ErrorResponseas{ error, code, ... }. Non-breaking, but it gives up the RFC 7807-shaped contract the schema was reaching for.Worth deciding before the SDKs grow more error-handling code against the current de-facto shape.