> 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` 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 what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.