Skip to main content

About Validation and Errors

NOTE Tasking API V2 is in final development and review. This draft documentation is subject to change at any time.

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 body 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 tasking headquarters for collection scheduling. The request status is updated to "INITIAL."

  • For "Fastview" requests, the requested start date and time are checked against the tasking reservation system schedule for availability. If the requested date and time are not available, a 400 bad request error is returned, with a list of alternative reservation times.

Validation Only request submission​

A request can be placed to only run the validation checks without submitting an order by adding the query parameter validation_only=true to your POST tasking request. This runs the same checks listed above, but does not submit the order if validation is successful.

.../tasking/vantor?validation_only=true

Example description for a schema validation error​

{
  "input": {
    "end_use_code": "AGR"
  },
  "type": "missing",
  "loc": [
    "body",
    "vantor_commercial",
    "flexView",
    "product_details",
    "ProductDetailsFastBestVantorCommercial",
    "product_licensing",
    "end_use_description"
  ],
  "msg": "Field required"
}

To quickly read this style of error message, start at the bottom with the msg field, and then look at the last item in the loc array. For the example above, it is saying "the required field 'end_use_description' is missing"

Example message for an availability error​

This error is only returned for Fastview requests when the requested start date/time is not available.

'start_collect_datetime' not available for collection.  available dates: ['2025-03-21', '2025-03-23', '2025-03-23', '2025-03-24', '2025-03-26', '2025-03-27', '2025-03-29']

Request is received by the tasking system​

Additional validation checks are run when the request is received.

  • 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 Vantor 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 Vantor Headquarters."

”Hub Tasking has received a 4xx response from the Vantor factory: {errorMessage}”

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

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

“Hub 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.

Note: A collection request from the 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 product_type in the product_details section of the Tasking request. During processing and delivery, there are additional validation checks that must be met. One examples of the validation checks that happen during the processing and delivery workflow is:

  • Delivery location (output_configs): If you are delivering to a cloud storage location, it must be valid and able to have data written to it. If access fails, the tasking request status will be updated to "CONTENT_PRODUCTION_FAILURE" and a notification will be sent.