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.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.Modified at 2024-08-20 12:39:07