Errors & Warnings

When working with the Edlink API, you'll eventually encounter errors and warnings. These are important to understand because they can help you troubleshoot and resolve issues with your requests. We've designed our error and warning system to be informative and easy to work with programmatically so you can handle them effectively.

It's important to note, we've also designed the system to be able to return multiple errors and warnings at once. This is to help you address all the problems before trying to send the request again.

Error Messages

One or more errors will result when the API encounters a situation that it cannot gracefully handle. You'll want to look at the details of each error to determine how to address them. Every error returned by the API will include a code and message field to aid you in correcting the problem.

Notice that multiple errors could be reported at once. This makes it possible to address multiple problems before trying to send the request again.

We will return a response body with the following structure when any errors occur:

{
    "$request": "00000000-0000-0000-0000-000000000000",
    "$errors": [
        {
            "code": "ERROR_CODE_EXAMPLE",
            "message": "This is a human-readable description of the error."
        }
    ]
}

Warning Messages

A warning results when the API wants to let you know about a situation that is not an error, but could still cause problems or unexpected results. Like errors, every warning returned by the API will include a code and message field to aid you in correcting the problem.

Warnings can be included in any API response, including alongside errors. We recommend that you monitor all responses for warnings. They appear in the following format:

{
    "$request": "00000000-0000-0000-0000-000000000000",
    "$data": [ ... ],
    "$warnings": [
        {
            "code": "WARNING_CODE_EXAMPLE",
            "message": "This is a human-readable description of the warning."
        }
    ]
}

OAuth 2.0 Authentication Errors

Errors can also occur during the OAuth 2.0 authentication flow (such as during Single Sign-On). If you have enabled the SSO Error Behavior feature flag, these errors are typically passed via the error query parameter in the redirect URI rather than as a JSON response body.

Common causes for these errors include:

• Client ID mismatches: This typically happens when the Client ID in the URL does not match the intended Integration or Application. Ensure you are using the correct credentials for the specific environment you are testing.
• Invalid State: The state parameter failed validation.
• Invalid Authorization Code: The code has expired or has already been used.