false<\/code> whenever the outcome is a property of the request itself, so that repeating it would fail the same way. Prefer this over inferring retryability from the status code: several conditions return 502 or 503 but are permanent. It is present on every JSON error response.<\/li>\n<\/ul>\nSo the contract is the HTTP status, the code<\/code>, retryable<\/code>, and the \u2020<\/strong> fields of data<\/code>. error<\/code> is what you put in front of a person, and the rest of data<\/code> is what you put in a log \u2014 those descriptions say what it holds today, not what it will always hold.
\nA request body sent with a JSON content type is parsed before the request reaches the endpoint. If it is not valid JSON, or is a JSON scalar rather than an object, the API answers 400<\/strong> with the code INVALID_JSON<\/code> and quotes the JSON parser’s diagnosis in error<\/code>. This is reported instead of, not in addition to, the endpoint’s own complaint about a missing field \u2014 a body that does not parse carries no fields at all, whatever it appears to contain. Take particular care to escape control characters inside JSON strings: a literal newline in a value, which is easy to introduce by interpolating a text field into a JSON template, makes the entire body unparseable and must be sent as \\n<\/code>.<\/p>\nRetrying<\/h2>\n
When retryable<\/code> is true<\/code> and the status is 503 or 504, the response also carries a Retry-After<\/code> header giving the number of seconds to wait. Retry with exponential backoff and give up after a few attempts; if a retryable error persists for more than a minute or two, treat it as an outage and open a support ticket rather than continuing to poll.<\/p>\nWhen retryable<\/code> is false<\/code>, repeating the request unchanged is pointless \u2014 the request, the flight plan, or the state of the resource has to change first. In particular a routing or parsing failure caused by the flight plan itself (PARSE_FAILED<\/code>) is never retryable, whereas a failure to reach the engine that would have parsed it (ROUTER_UNREACHABLE<\/code>, ROUTER_BUSY<\/code>) always is.
\nA small number of endpoints \u2014 mostly authentication\/authorization failures raised by shared middleware \u2014 return only the HTTP status code with an empty body, rather than the JSON shape above. This is noted explicitly wherever it applies below. Treat any endpoint that returns 401 or 403 as potentially body-less unless the endpoint’s table says otherwise.<\/p>\nThe \/oauth2\/token<\/code> endpoint is a deliberate exception: because it implements the OAuth 2.0<\/a> specification, its error responses follow the OAuth2 error shape instead of the shape above \u2014 see the Authentication<\/a> section.<\/p>\nHTTP status codes<\/h2>\n
\n\n\n| Status<\/th>\n | Meaning<\/th>\n<\/tr>\n<\/thead>\n |
\n\n200<\/strong><\/td>\n| Request completed successfully.<\/td>\n<\/tr>\n | \n400<\/strong><\/td>\n| Invalid request data. Some of the data passed to the call is not valid.<\/td>\n<\/tr>\n | \n401<\/strong><\/td>\n| Not authorized. You supplied no credentials, expired credentials, or invalid credentials. Retry with correct credentials.<\/td>\n<\/tr>\n | \n403<\/strong><\/td>\n| Access denied. You do not have permission to access the resource or perform the operation. Repeating the request will not help.<\/td>\n<\/tr>\n | \n404<\/strong><\/td>\n| Object not found. Most likely an object referenced through the request URL was not found, or could not be accessed due to insufficient privileges.<\/td>\n<\/tr>\n | \n409<\/strong><\/td>\n| Conflict. The request could not be completed because it conflicts with the current state of the resource (for example, filing a flight plan that has already been filed). Repeating the request unchanged will not help; the underlying state must change first.<\/td>\n<\/tr>\n | \n422<\/strong><\/td>\n| Unprocessable entity. The request was well-formed but failed validation (for example, a flight plan that does not pass IFPS validation or was rejected by Eurocontrol). The response body contains details on what failed.<\/td>\n<\/tr>\n | \n429<\/strong><\/td>\n| Too many requests. You have exceeded a rate limit or a plan limit. Wait before retrying.<\/td>\n<\/tr>\n | \n500<\/strong><\/td>\n| Internal error processing the request. Please report this along with the scenario that triggered it.<\/td>\n<\/tr>\n | \n502<\/strong><\/td>\nBad gateway. An upstream system the request depends on (for example Eurocontrol\/IFPS, the AFTN gateway) returned an invalid or unexpected response. Do not assume this is temporary \u2014 most 502s here are permanent, and retryable<\/code> is what tells you which one you have.<\/td>\n<\/tr>\n\n503<\/strong><\/td>\n| The server cannot handle the request at this time due to capacity or connectivity issues. Retry later; open a support ticket if this persists.<\/td>\n<\/tr>\n | \n504<\/strong><\/td>\nGateway timeout. An upstream system the request depends on did not respond in time. The request can be retried.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\nStable error codes<\/h2>\nThe table below lists every stable code<\/code> value currently defined, grouped by category, together with the HTTP status it is normally paired with and whether the condition is worth retrying. The Retryable<\/em> column matches the retryable<\/code> field of the response body exactly. These are used most extensively by the Flightplans<\/a> API; a handful are also used by the Routes<\/a> and Aircraft<\/a> APIs. Endpoints that reference one of these codes are noted in their section below.<\/p>\n\n\n\n| Code<\/th>\n | Status<\/th>\n | Retryable<\/th>\n | Meaning<\/th>\n<\/tr>\n<\/thead>\n | \n\nAuthorization \/ access<\/em><\/td>\n<\/tr>\n\nNOT_AUTHORIZED<\/code><\/td>\n| 403<\/td>\n | no<\/td>\n | You are not authorized to perform this operation (for example, no filing privileges, or acting on behalf of a user without delegation).<\/td>\n<\/tr>\n | \nFLIGHTPLAN_NOT_FOUND<\/code><\/td>\n| 404<\/td>\n | no<\/td>\n | The referenced flight plan does not exist, or you do not have access to it.<\/td>\n<\/tr>\n | \nROUTE_NOT_FOUND<\/code><\/td>\n| 404<\/td>\n | no<\/td>\n | The referenced route does not exist, or you do not have access to it.<\/td>\n<\/tr>\n | \nBad request \/ state<\/em><\/td>\n<\/tr>\n\nINVALID_JSON<\/code><\/td>\n| 400<\/td>\n | no<\/td>\n | The request body was sent with a JSON content type but is not valid JSON, or is a JSON scalar rather than an object. Can be returned by any endpoint that takes a body; error<\/code> carries the parser’s diagnosis, for example an unescaped control character inside a string.<\/td>\n<\/tr>\n\nINVALID_BRIEFING<\/code><\/td>\n| 400<\/td>\n | no<\/td>\n | Required briefing information was not supplied when filing.<\/td>\n<\/tr>\n | \nINVALID_CUSTOMERREF<\/code><\/td>\n| 400<\/td>\n | no<\/td>\n | The customerref<\/code> supplied when filing cannot be stored as sent: it is not a string, not valid UTF-8, longer than 64 characters, or contains control characters (a newline, for example). The value is otherwise opaque to us and is stored exactly as sent, which is why an unusable one is refused rather than adjusted. Surrounding whitespace is trimmed, and an empty reference is treated as none at all.<\/td>\n<\/tr>\n\nINVALID_TIME<\/code><\/td>\n| 400<\/td>\n | no<\/td>\n | A supplied time (e.g. departure\/arrival time) is invalid.<\/td>\n<\/tr>\n | \nEOBT_OUT_OF_RANGE<\/code><\/td>\n| 400<\/td>\n | no<\/td>\n | The requested EOBT is outside the range allowed for the operation.<\/td>\n<\/tr>\n | \nPLAN_LIMIT_EXCEEDED<\/code><\/td>\n| 429<\/td>\n | no<\/td>\n | You have reached the maximum number of active flight plans allowed for your account. Waiting does not help \u2014 the limit only clears when one of your plans is closed.<\/td>\n<\/tr>\n | \nWRONG_STATE<\/code><\/td>\n| 409<\/td>\n | no<\/td>\n | The flight plan is not in a state that allows this operation (for example, sending an arrival message for a plan that is not filed).<\/td>\n<\/tr>\n | \nDUPLICATE_FILING<\/code><\/td>\n| 409<\/td>\n | no<\/td>\n | A matching flight plan or route has already been filed\/created. Where the duplicate is one we detected ourselves \u2014 an AFTN or LVNL filing matching an active plan of yours \u2014 data.fplid<\/code> \u2020<\/strong> is the flight ID of the plan in the way, the same ID the \/flightplan\/file\/{flightid}\/\u2026<\/code> operations take. Where Eurocontrol reports the conflict instead, we look for a live plan of yours matching the flight and include fplid<\/code> the same way when we find one, but that one is unmarked: the conflict can be a plan filed for the aircraft by somebody else, and Eurocontrol matches a time frame where we match an exact EOBT, so it is not always there. On route creation there is no such id at all.<\/td>\n<\/tr>\n\nALREADY_CANCELLED<\/code><\/td>\n| 409<\/td>\n | no<\/td>\n | The flight plan was already cancelled (including externally, e.g. by ATC).<\/td>\n<\/tr>\n | \nValidation<\/em><\/td>\n<\/tr>\n\nVALIDATION_FAILED<\/code><\/td>\n| 422<\/td>\n | no<\/td>\n | The flight plan does not validate under the new parameters (for example, cannot be brought forward to the requested time).<\/td>\n<\/tr>\n | \nFILING_VALIDATION_FAILED<\/code><\/td>\n| 422<\/td>\n | no<\/td>\n | The flight plan failed final validation prior to filing. The validator’s output is part of error<\/code>, one CODE: description<\/code> per line, and can be shown as it stands; data.ifpserrors<\/code> currently breaks the same errors up the way an IFPS rejection<\/a> does, unmarked for now. Filing again with \"force\": true<\/code> submits the plan anyway, which may put it into the manual queue at Eurocontrol.<\/td>\n<\/tr>\n\nNOT_IFPS_APPLICABLE<\/code><\/td>\n| 422<\/td>\n | no<\/td>\n | The flight plan does not contain an IFR segment within the Eurocontrol region and cannot be accepted for IFPS filing.<\/td>\n<\/tr>\n | \nFILING_REJECTED<\/code><\/td>\n| 422<\/td>\n | no<\/td>\n | Eurocontrol\/IFPS rejected the message \u2014 the flight plan on filing, or the cancellation, delay, departure or arrival message on the corresponding endpoint. error<\/code> names every reason IFPS gave, and data.ifpserrors<\/code> \u2020<\/strong> lists them field by field, see IFPS rejections<\/a>.<\/td>\n<\/tr>\n\nUpstream \/ infrastructure<\/em><\/td>\n<\/tr>\n\nPARSE_TIMEOUT<\/code><\/td>\n| 504<\/td>\n | yes<\/strong><\/td>\n| The flight plan parser did not return a result in time.<\/td>\n<\/tr>\n | \nPARSE_FAILED<\/code><\/td>\n| 422 or 502<\/td>\n | no<\/td>\n | The flight plan itself could not be parsed \u2014 422 for a structurally invalid plan (e.g. a non-existent airway segment), 502 when the parser accepted it but returned no usable result. Submitting the same plan again gives the same outcome. Where the parser produced structured errors, data<\/code> carries them as error2<\/code>, the same structure a successful parse returns them in. This code is never<\/strong> used for a failure to reach the parsing engine; those get ROUTER_UNREACHABLE<\/code>, ROUTER_BUSY<\/code> or ROUTER_ERROR<\/code>.<\/td>\n<\/tr>\n\nEUROCONTROL_ERROR<\/code><\/td>\n| 502<\/td>\n | no<\/td>\n | Eurocontrol\/NM B2B returned an invalid, unexpected, or permanently failing response. The NM reply status and its explanation, where NM gave one, are part of error<\/code>; data<\/code> repeats them for your log. Please report these \u2014 they generally mean something on our side or NM’s needs fixing.<\/td>\n<\/tr>\n\nEUROCONTROL_UNAVAILABLE<\/code><\/td>\n| 503<\/td>\n | yes<\/strong><\/td>\nEurocontrol could not be reached, or reported a momentary condition of its own (SERVICE_UNAVAILABLE<\/code>, RESOURCE_OVERLOAD<\/code>, a quota that resets). Nothing was sent \u2014 retry shortly, honouring Retry-After<\/code>.<\/td>\n<\/tr>\n\nAFTN_SEND_FAILED<\/code><\/td>\n| 502<\/td>\n | no<\/td>\n | An AFTN message could not be sent (invalid input, or a permanent gateway failure).<\/td>\n<\/tr>\n | \nAFTN_GATEWAY_UNREACHABLE<\/code><\/td>\n| 503<\/td>\n | yes<\/strong><\/td>\n| The AFTN gateway is temporarily unreachable; nothing was sent. Retry shortly.<\/td>\n<\/tr>\n | \nLVNL_SEND_FAILED<\/code><\/td>\n| 502<\/td>\n | no<\/td>\n | A message to LVNL (Dutch ANSP) could not be sent.<\/td>\n<\/tr>\n | \nLVNL_PILOT_TEL_MISSING<\/code><\/td>\n| 422<\/td>\n | no<\/td>\n | LVNL requires a pilot telephone number for Dutch VFR departures, and none was supplied on the flight plan.<\/td>\n<\/tr>\n | \nREFILE_FAILED<\/code><\/td>\n| 500<\/td>\n | no<\/td>\n | Refiling a modified flight plan failed after the original was already cancelled\/changed.<\/td>\n<\/tr>\n | \nPERSIST_FAILED<\/code><\/td>\n| 500<\/td>\n | no<\/td>\n | The flight plan was accepted upstream but could not be persisted on our side.<\/td>\n<\/tr>\n | \nINTERNAL_ERROR<\/code><\/td>\n| 500<\/td>\n | no<\/td>\n | Generic internal server error. Used when no more specific code applies.<\/td>\n<\/tr>\n | \nROUTER_UNREACHABLE<\/code><\/td>\n| 503<\/td>\n | yes<\/strong><\/td>\nThe routing or parsing engine could not be reached at all \u2014 no engine available, name resolution failure, connection refused, or the connection dropped mid-exchange. Purely an infrastructure condition: there is nothing wrong with your request and the same request will normally succeed once the engine is back. Retry after the interval in Retry-After<\/code>.<\/td>\n<\/tr>\n\nROUTER_BUSY<\/code><\/td>\n| 503<\/td>\n | yes<\/strong><\/td>\nThe routing or parsing engine was reached but is at capacity and refused the work. Retry after the interval in Retry-After<\/code>.<\/td>\n<\/tr>\n\nROUTER_TIMEOUT<\/code><\/td>\n| 504<\/td>\n | yes<\/strong><\/td>\n| The routing engine was reached but did not produce a result in time.<\/td>\n<\/tr>\n | \nROUTER_ERROR<\/code><\/td>\n| 502<\/td>\n | no<\/td>\n | The routing engine returned an unexpected, malformed or invalid response, or rejected what was sent to it. Retrying produces the same result \u2014 please report this.<\/td>\n<\/tr>\n | \n | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |