> For the complete documentation index, see [llms.txt](https://synap.ac/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://synap.ac/docs/api/error-handling.md). # Error Handling ### JSON:API Error Specification The Synap API follows the [JSON:API Error specification](https://jsonapi.org/format/#error-objects), ensuring that error responses are consistent and structured. Each error object in the response includes key details such as an HTTP status code, an error type, a descriptive message, and optionally, additional context like error codes, source, and metadata for support-requests. ### HTTP Status Codes The API utilises standard HTTP status codes to indicate the outcome of requests. Success is typically indicated by `200 OK`, while errors like `400 Bad Request` are used for issues such as invalid input. The use of well-known status codes allows developers to quickly understand the nature of the error. ### Validation Errors When a request fails due to invalid data, the API returns a `400 Bad Request` status with a detailed error object that includes information about each validation error. This should help you quickly identify which parts of the request need correction. ### Authentication and Authorisation Errors Errors related to authentication and authorisation are clearly indicated by `401 Unauthorised` and `403 Forbidden` status codes, respectively. The accompanying error object provides additional context, such as which credentials were missing or why the action was denied. An example of a `403 Forbidden` response would be one where you try to perform a disallowed action, such as marking an Exam that is still in draft. ### Server Errors In rare cases where the Synap API runs into server errors, a response with `5xx` status codes will be returned. A `500 Internal Server Error` indicates an unexpected issue on our end. You should retry these at least once, but persistent failures would suggest a reportable bug; please get in touch if you come across this type of error and make note of the `traceId` which we include the the response payload. Our engineers can use this `traceId` to more quickly locate, and resolve your issue. Transient server errors such as `502 Bad Gateway`, `503 Service Unavailable`, and `504 Gateway Timeout`, signal temporary problems. In these cases, you should attempt a reasonable amount of retries with an exponential backoff strategy. Although there is no single answer here, however we recommend up to 5 retries with at least a 2 to 15 second delay between each. ### Endpoint-Specific Error Information Each API endpoint’s documentation includes a list of possible error status codes that might be returned. At this point in the Synap API journey, the level of detail in each endpoint for possible errors is limited. We plan on expanding in this area as the usage of our API expands to more customers. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://synap.ac/docs/api/error-handling.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.