Skip to main content

About Validation and Errors

Validation occurs at multiple points during the tasking fulfillment process. There are two types of validation:

  • Synchronous validation occurs at the time the tasking request is submitted. Any resulting errors are returned in the API response.
  • Asynchronous validation occurs after the tasking request has been submitted. Asynchronous checks are made at multiple stages in the acceptance, collection, processing, and delivery workflow. When an asynchronous error occurs, a notification is sent based on the instructions provided in the "notifications" section of the tasking request.

Tasking request submission​

The Tasking API runs a series of validation checks at the time the request is submitted. This step primarily checks to make sure the JSON boy is formatted correctly, the required fields are included, the AOI size requirements are adhered to, and the submitted values are allowed.

  • If validation fails, a 400 BAD REQUEST error is returned with a description of the issue.

  • If validation succeeds, the request submission is sent to Maxar tasking headquarters for collection scheduling. The request status is updated to "INITIAL."

Example error descriptions for a 400 Bad Request response:​

start_datetime must occur at least 5 minutes into the future

aoi_geojson must be type Polygon

max_cloud_cover must be between 15 and 50

max_off_nadir_angle must be between 5 and 45

collect_gsd must be one of the following values: [0.5, 0.3].


pipeline must be one of the following values: ['imagery/system-ready', 'imagery/view-ready', 'imagery/view-ready-ortho', 'imagery/map-ready']

order_templates.settings.inventory_ids must be set to ['$.id']"

order_templates.settings.aoi must be set to '$._aoi_intersection'"
      
end_use_code must be one of the following values: ['AGR', 'DEM', 'DNI', 'DPE', 'DPP', 'EDU', 'ENV', 'ERM', 'FAC', 'FGV', 'FIN', 'HUM', 'HYD', 'LBS', 'MAR', 'MIN', 'NAT', 'OTH', 'PIP', 'RED', 'RUR', 'SAW', 'SHL', 'SIM', 'TEL', 'URB', 'USG', 'VIS']."    

tasking_priority must be one of the following values: ['Select', 'SelectPlus']

Request is received by Maxar tasking headquarters​

Additional validation checks are run when the request is received by Maxar headquarters.

  • If successful, the status of the API request will be updated to "ACCEPTED" and a notification is sent based on the instructions in the "notifications" section of the Tasking request with the following message:
"Tasking has been accepted with Maxar Headquarters."
  • If the request is not accepted, it will be updated to a status of DENIED and a notification will be sent with one of the following messages. The {errorMessage} section may provide additional details for troubleshooting.
"Request has stalled at INITIAL state for more than 24 hours. Moving to DENIED state."

"Tasking has been denied by Maxar Headquarters."

”MGP Tasking has received a 4xx response from the Maxar factory: {errorMessage}”

"MGP Tasking has received a 5xx response from the Maxar factory: {errorMessage}”

“Maxar Factory has rejected the request: {errorMessage}”

“MGP Tasking has failed to successfully create a monitor: {errorMessage}”

Request is scheduled but not collected within the specified timeframe​

If a collection request was scheduled but either not fulfilled or only partly fulfilled during the specified timeframe, the status will be updated to "UNFULFILLED or "PARTIALLY FULFILLED." A notification will be sent with the error message:

"Process error - the request has prematurely expired. Content has been produced, delivered, and billed for {tasking.billed_percent}% of the total tasking aoi."

This can happen if the tasking parameters are constrained and the requested conditions couldn't be met. For example, a request for imagery with maximum 5% cloud cover during a cloudy week will probably not be collected. See Maximizing Collection Opportunities for more examples.

Note: A collection request from the MGP Tasking API cannot be extended. If collection is still needed, a new request should be sent.

Imagery is collected and is ready to be processed and delivered​

Once the imagery is collected, it is ready to be processed and delivered based on the instructions in the order_templates section of the Tasking request. During processing and delivery, there are additional validation checks that must be met. Examples of validation checks that happen during the processing and delivery workflow are:

  • Core imagery recipes: The default core imagery recipes are set up for successful order processing. It is possible to override the values in the default recipes, but the override values and default values may be mismatched, causing a processing failure. For this reason, we don't recommend adding overrides to the settings in a tasking request. If a mismatch is found during processing, the tasking request status will be updated to "CONTENT_PRODUCTION_FAILURE" and a notification will be sent.

  • Delivery location (output_configs): The delivery location specified in your tasking request must be valid and MGP must be able to write data to it. Follow the steps in the Cloud Storage Setup documentation before submitting a Tasking request. If MGP can't write data to your bucket, the tasking request status will be updated to "CONTENT_PRODUCTION_FAILURE" and a notification will be sent.

When a content production failure occurs, a notification is sent with the following message:

"Content has failed to be delivered. CAT_ID: {cat_id}. MGP Order ID: {mgp_order_id}"