This document provides a general overview of potential errors and issues that might occur while utilizing the Subscriptions API. It highlights various categories of errors such as syntax errors, data format discrepancies, and potential source issues, offering a preliminary understanding of the nature of these errors. It is important to note that this is not a comprehensive list, but rather a guide to give users a general idea of potential issues they might encounter. Users are encouraged to consult the detailed API documentation for a more exhaustive understanding and troubleshooting guidance.

Request failed schema validation¶

HTTP status code: 400

This may return, but is not limited to:

{
  "error": {
    "reason": "Request failed schema validation",
    "details": [] 
  }
}

It is crucial to adhere to the expected request body structure as defined in the API reference. Errors in the request body can lead to a schema validation error. Some examples of errors that may trigger schema validation errors, include, but are not limited to:

Syntax Errors:¶

Mismatched Parentheses or Brackets: Ensure that all opening brackets ({, [) have corresponding closing brackets (}, ]) and that they are nested correctly.
Missing Commas: Ensure that elements in arrays and properties in objects are separated by commas.

Spelling Mistakes:¶

Incorrect Property Names: Ensure that property names are spelled correctly as per the API documentation.

Data Format Errors:¶

Incorrect Date Format: Dates should be formatted as per the ISO 8601 standard, i.e. YYYY-MM-DDTHH:MM:SSZ. For example, 2021-03-01T00:00:00Z is a valid date, whereas 2021/03/01 00:00:00 is not.
Invalid Data Types: Ensure that the data types for each property match the expected data types as per the API documentation. For instance, if a property expects a string, it should not receive an int or an array.

Bad requests¶

HTTP status code: 400

This may return a number of errors, including but not limited to:

{
  "error": {
    "reason": "Problem with request",
    "details": [] 
  }
}

This error is a general indication that there was an issue with the setup or structure of your API request. Here are some potential causes and how to avoid them:

Invalid Cloud Delivery Settings:¶

Invalid Credentials: Ensure that the credentials provided in the cloud delivery settings are accurate and have the necessary permissions. Incorrect credentials can prevent the API from authenticating and processing your request successfully.
Incorrect Delivery Destination: Verify that the cloud delivery settings (e.g. bucket) are correctly configured. An incorrect setup can lead to failures.

Request Structure and Data Issues:¶

Incomplete Request Body: Ensure that the request body is complete and includes all the necessary parameters. Missing parameters can cause the request to fail.
Tools are used in an appropriate way. For example, bandmath supports the pixel types ‘8U, 16U, 16S, 32R, and auto’ and may trigger this error if the pixel type input is incorrect.
Backfill not allowed: Backfill goes beyond what is allowed for the user’s account. Ensure the date range is correct.
Planetary Variables:
- The source IDs for planetary variables that you have requested and will appear on your account dashboard must be correct or could cause an error.
- The source type for planetary variables must be correct and match the corresponding source ID.

Invalid Asset Type (catalog subscriptions):¶

If the asset_types field contains an unsupported or non-existent asset type, the request will fail. For instance, specifying an asset type that doesn't match any of the asset types available in the satellite imagery database. You should verify that the asset types specified in the request (like ortho_analytic_4b) are valid and supported by the API.

Incorrect Item Type (catalog subscriptions):¶

Similar to the asset type, specifying an incorrect item type in the item_types field can cause a problem. You should ensure that the item types specified (like PSScene) are valid and supported by the API.
Start Time After End Time: If the start_time is specified to be a time after the end_time, it will be rejected.
Unsupported Recurrence Rules: If the subscription source supports recurrence rules and you specify a rule that is not supported or is syntactically incorrect, it can cause an error.
Invalid Geometry Coordinates: Specifying a geometry with coordinates that is not valid GeoJSON can be another source problem. This might include coordinates that do not close to form a loop or coordinates that cross over each other, forming an invalid shape.

Unauthenticated¶

HTTP status code: 401

This error may be displayed when the system can’t verify the validity of the user.

API key¶

This may return:

API key not found

Requests may be rejected when the API key entered is invalid.

Unauthorized¶

HTTP status code: 403

This error may be displayed when the user does not have permission to access the requested resource.

Requested product(s) or geographies are not provisioned for the user.
User is not authorized to take the requested action.

Internal server error¶

HTTP status code: 500

Something went wrong while the server was processing the request.