Error Handling

Introduction

This page is intended to offer some guidance when it comes to how API solutions should interpret, respond, and handle errors.

Error Codes

HTTP 400 – Bad Request

Our server was unable to process the request sent due to invalid syntax.

Example of Error Response Data

{
  "meta" : {
    "errors" : [ {
      "title" : "??? No message available ???",
      "code" : "ERR_INPUT_MISSING"
    } ],
    "warnings" : [ ],
    "infos" : [ ]
  }
}

Suggested Handling

There could be an array of reasons why this error would be generated, but in most circumstances it could relate to the header information that is being sent in the call.

  • We suggest a built-in waiting period of at least 5-10 minutes between retries after receiving this error.
  • A message to the user, i.e. “The request is invalid”.

HTTP 401 – Unauthorized

Our server has received a request and could not respond due to unauthenticated/invalid credentials.

Example of Error Response Data

{
    "meta": {
        "errors": [
            {
                "title": "Invalid value for header: Authorization",
                "code": "ERR_INPUT_GENERIC_INVALID"
            }
        ],
        "warnings": [],
        "infos": []
    }
}

Suggested Handling

  • A message to the user, i.e. “The provided credentials seem to be invalid. Please verify the information provided and/or contact support if the problem persists”.
  • Encourage or give the user the possibility to review/change the data/payload that is generating the error prior to retry.
  • For automated requests: we suggest a built-in waiting period of at least 5-10 minutes between retries after receiving this error.

HTTP 403 – Forbidden

Our server has received a request that is authenticated, but there could be:

  • Limitations or access permissions imposed on this endpoint, for which you have not been granted.
  • The aircraft tail you are trying upload schedule data for may not be configured, or in a state for which it is unable to receive this data.

Example of Error Response Data

{
  "meta" : {
    "errors" : [ {
      "title" : "Search API access",
      "code" : "AUTHORIZATION_PERMISSIONS"
    } ],
    "warnings" : [ ],
    "infos" : [ ]
  }
}
{
  "meta" : {
    "errors" : [ {
      "title" : "XXXXX - The aircraft is configured for manual schedule updates.",
      "code" : "ERR_INPUT_GENERIC_INVALID"
    } ],
    "warnings" : [ ],
    "infos" : [ ]
  },
  "data" : { }
}

Suggested Handling

  • We suggest a built-in waiting period of at least 5-10 minutes between retries after receiving this error. If this is related to a specific aircraft tail, the system should skip to the next tail in the sequence, rather than retrying the same tail.
  • If the error message pertains to limitations (point a) or permissions, a message to the user, i.e. “You do not have permissions for this resource, or some restrictions apply”
  • If the error message pertains to aircraft state (point b), a message to the user, i.e. “This aircraft [aircraftTail] is not configured correctly to receive this request”

HTTP 404 – Not Found

Our server has received a request to a resource/endpoint that cannot be found.

This could be due to:

  • Resource/endpoint does not exist
  • Resource/endpoint has been (re)moved
  • Resource/endpoint has not been created
  • The request data payload is empty for an endpoint where payload is expected (see second example of error response data).

Example of Error Response Data

{
    "meta": {
        "errors": [
            {
                "title": "Not found",
                "code": "NOT_FOUND"
            }
        ],
        "warnings": [],
        "infos": []
    }
}
{
  "meta" : {
    "errors" : [ ],
    "warnings" : [ ],
    "infos" : [ ]
  }
}

Suggested Handling

  • We suggest a built-in waiting period of at least 5-10 minutes between retries after receiving this error.
  • A message to the user, i.e. “The resource/endpoint you are trying to access cannot be found”, or in the case of empty error response, “The resource/endpoint you are trying to access requires payload data but the submitted request data was empty”.

HTTP 405 – Method Not Allowed

Our server has received a request to a resource/endpoint, but the attempted connection method is not accepted or valid.

This could be due to an invalid use of GET, POST, PUT, DELETE methods. It is a common mistake that POST instead of PUT method is attempted for schedule data uploads.

Example of Error Response Data

{
    "meta": {
        "errors": [
            {
                "title": "Unfortunately the application has experienced an error. Please try again later or contact us.",
                "code": "ERR_INTERNAL_CRITICAL"
            }
        ],
        "warnings": [],
        "infos": []
    }
}

Suggested Handling

  • We suggest a built-in waiting period of at least 15-30 minutes between retries after receiving this error.
  • A message to the user, i.e. “The server cannot accept the connection method sent in the request”
  • Additionally, we suggest some sort of logging (time, date, method, endpoint, potential payload) and notifying of this error in your back-end, as this will probably be related to accepted connection methods.

HTTP 422 – Unprocessable Entity

Our server has received a request that is authenticated, the call is allowed, but the content or format of the call is not fully understood and is unable to process.

This could be due to:

  • The aircraft tail referenced in the payload doesn’t exist or is set to inactive in Avinode.
    See Example A
  • The resource URL submitted in the request payload is already in use in the system. This could be applicable to i.e. webhook URLs.
    See Example B
  • The input parameters do not conform to the expected payload format and can not be processed.
    See Example C

Example of Error Response Data

{
  "meta" : {
    "errors" : [ {
      "title" : "??? No message available ???",
      "code" : "ERR_INPUT_MISSING"
    } ],
    "warnings" : [ ],
    "infos" : [ ]
  }
}
{
  "meta" : {
    "errors" : [ {
      "title" : "Field \"URL\" is invalid.  The URL https://example.webhook.website.url/ is already in use in the system, please provide a unique URL to continue.",
      "code" : "ERR_PERSIST_CONSTRAINT_VIOLATED",
      "status" : 422,
      "path" : "targetURI"
    } ],
    "warnings" : [ ],
    "infos" : [ ]
  }
}
{
    "meta": {
        "errors": [
            {
                "title": "The input JSON could not be parsed to the expected format.",
                "code": "ERR_INPUT_INVALID_JSON"
            }
        ],
        "warnings": [],
        "infos": []
    }
}

Suggested Handling

  • We suggest a built-in waiting period of at least 15-30 minutes between retries after receiving this error.
  • A message to the user, i.e. “The server cannot process the request”
  • Additionally, we suggest some sort of logging (time, date, endpoint, potential payload) and notifying of this error in your back-end, as this will probably be related to the way the data is formatted in the payload and may need a review by your developers.

HTTP 429 – Too Many Requests

Our server has received too many requests to the same endpoint over a given period and the rate-limits have been exceeded. Read more about our Service Rate Limits.

Example of Error Response Data

{
  "meta" : {
    "errors" : [ {
      "title" : "Rate limit exceeded."
    } ],
    "warnings" : [ ],
    "infos" : [ ]
  }
}

Suggested Handling

  • We suggest a built-in waiting period before a retry is made, after receiving this error. The rate limit at which the service rate limit was reached, remaining calls left, and time until limit reset are often returned in the response header in the following parameters:
X-Rate-Limit-Limit  The rate limit for the endpoint that was invoked as the number of allowed calls.
X-Rate-Limit-Remaining  The remaining number of  calls allowed for the service.
X-Rate-Limit-Reset  The number of seconds until the call counter is reset.
  • A message to the user, i.e. “Too many requests have been made to this resource over a given period – retries have been paused for/until X (time frame)”. 

HTTP 500 – Internal Server Error

Something has gone wrong on our server.

Example of Error Response Data

{
    "meta": {
        "errors": [
            {
                "title": "Unfortunately the application has experienced an error. Please try again later or contact us.",
                "code": "ERR_INTERNAL_CRITICAL"
            }
        ],
        "warnings": [],
        "infos": []
    }
}

Suggested Handling

  • This is a very generic error and can be caused by various reasons. We suggest a built-in waiting period of at least 3-5 minutes before retrying.
  • A message to the user, i.e. “An internal server error has occurred”
  • Additionally, we suggest some sort of logging (time, date, endpoint, potential header/payload data) and notifying of this error in your back-end. This can help when relaying the information to Avinode, should the error persist over a longer period of time/retries.