Error Handling

JSON:API Error Specification

The Synap API follows the JSON:API Error specification, 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.

JSON:API Error Specification#

HTTP Status Codes#

Validation Errors#

Authentication and Authorisation Errors#