Error Handling
This page is intended to offer some guidance when it comes to how API solutions should interpret, respond, and handle errors.
Error Codes
HTTP 200 + Errors
This error is a "soft error", which means the operation was successful, i.e. an entity was updated, however the data sent was not found to be valid in some way. The response data will contain information of what part of the json contained the invalid data.
Example of Error Response data
{
"meta": {
"errors": [
{
"title": "Invalid start airport",
"code": "START_AIRPORT_INVALID",
"path": "activities[1].startAirport"
}
],
"warnings": [],
"infos": []
},
"data": {}
}
{
"meta": {
"errors": [
{
"title": "Invalid end airport",
"code": "END_AIRPORT_INVALID",
"path": "activities[1].endAirport"
}
],
"warnings": [],
"infos": []
},
"data": {}
}
HTTP 400 – Bad Request
Our server was unable to process the request sent due to invalid syntax.
Note: The most common reason for this error is the omission of the X-Avinode-SentTimestamp in the header of the API call.
Example of Error Response Data
{
"meta" : {
"errors" : [ {
"title" : "??? No message available ???",
"code" : "ERR_INPUT_MISSING"
} ],
"warnings" : [ ],
"infos" : [ ]
}
}
{
"meta": {
"errors": [
{
"title": "The header 'X-Avinode-SentTimestamp' is required",
"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" : "{aircraftTail} - 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)
- The calling account is attempting to access a resource that doesn't belong to it
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 - The input value exceeds the max length.
See example D
Example of Error Response Data
{
"meta": {
"errors": [
{
"title": "No such marketed aircraft: {aircraftTail}",
"code": "MISSING",
"path": "lift.aircraftTail"
}
],
"warnings": [],
"infos": []
},
"data": {}
}
{
"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": []
}
}
{
"meta": {
"errors": [
{
"title": "The value exceeds the max length: 512",
"code": "ERR_INPUT_MAX_LENGTH",
"path": "activities[X].note"
}
],
"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.
Updated 8 months ago