I’ve taken a look at the official docs with some examples like:
And there it is the response for a successful request. But I wonder if there are docs that show the error objects expected to handle them better.
Hello @sergiof
I wonder if there are docs that show the error objects expected to handle them better
I’m not sure what you’re saying. The REST API documentation already contains the error response codes (objects) that can be expected when making a request to any of those endpoints.
If your app receives any of those error codes back in response to a request, it’s up to your app to ‘handle’ that error.
What I meant is the error response body schema, not the HTTP status codes.
For example, Confluence REST API v1 documents the error object structure explicitly.
However, for REST API v2 I couldn’t find any official documentation describing the error
response schema (fields).
From empirical testing, v2 returns errors like this:
{
"errors": [
{
"status": 409,
"code": "CONFLICT",
"title": "Version must be incremented when updating a page. Current Version: [5]. Provided version: [5]",
"detail": null
}
]
}
My concern is that this schema is not documented anywhere, so consumers are forced to
handle errors based on observed behavior rather than an officially defined contract.
Is there any official documentation or OpenAPI reference that defines the error response
schema for Confluence REST API v2?
OK, well that is a more meaningful description of what you are looking for.
As far as I am aware, the Confluence v2 REST API’s error response ‘object structure’ (as per that link you provided) is identical to the v1 REST API. The v2 endpoints are just a superset of new endpoints that will gradually replace the v1 endpoints.
If you want the OpenAPI definition files for both the v1 and v2 APIs, just download them from the documentation pages (click the icon in the top right corner). That is Atlassian’s ‘official’ level of detail they provide about the endpoints and their advertised errors
Apart from that, I’m not aware of any other ‘schema’ document that describes every single possible error response and its body structure (including the actual error message) that can be expected for all the different API endpoints, so yes indeed, “consumers are forced to handle errors based on observed behaviour rather than an officially defined contract”, pretty much as you’ve described.
When you asked Google / ChatGPT / other public AI about the existence of such error response schema documentation, did it advise you if it existed and where to find it? Were you able to find any previous threads when you searched this forum on the topic?