What JSON schema should our API responses follow in error scenarios?

[seancolsen]

Seeking a decision, or clarity if such a decision already exists.

I'm seeing some inconsistency in the API response schemas for error scenarios, and I'd like to know what the expected format is for API error responses so that I can open tickets when I notice APIs that do not conform.

Sometimes I see:

["Error message"]

Other times:

{"detail":"Error message"}

@mathemancer @kgodey

[seancolsen]

I have a slight preference for returning an object instead of an array, because it allows us to add other data to the error response if necessary. If we use an object, I'd like to ensure we always use the same key. The key detail which I'm already observing seems fine as long as we stick to it. But I haven't conducted a very exhaustive sampling of our APIs to determine how prevalent the detail key is. If we're starting from scratch, I'd probably pick a more intuitive key like error or message or msg.

[kgodey]

We don't have this figured out yet, we have an issue open for it, #560. We're mostly using DRF's standard errors, see: https://www.django-rest-framework.org/api-guide/exceptions/.

[seancolsen]

Thanks, I'll continue this discussion in the ticket.