Error handling

Recommendations for error handling

When invoking API operations, we recommend the following error handling practices:

  • When sending an API request, enable the problem details error format, by including application/problem+json in the Accept header (HTTP content negotiation).

HTTP content negotation

To receive more detailed and informative error responses, you can enable the problem details format (following RFC 7807) using HTTP content negotiation. The problem details format is enabled by including application/problem+json in the Accept header, as shown in the following table.

HTTP header Description

Accept: application/problem+json

Enables the problem details format in error responses.

Accept: application/json, application/problem+json

Accepts JSON format in the body of successful responses and enables the problem details format in error responses.

For example, the following curl command invokes the getContract operation with the problem details format enabled:

curl --location "${API_BASE_URL}/api/company/v1/contracts/${contractID}" \
--header "Accept: application/json, application/problem+json" \
--header "Authorization: Bearer ${API_ACCESS_TOKEN}"

Error response formats

The body of an error response can be returned in one of the following formats (depending on the settings for HTTP content negotiation).

  • Problem details format

  • Default format

Problem details format

If the API request has a HTTP Accept header that includes application/problem+json, the error response is returned in the following format:

{
    "title": "Contract Not Found",
    "code": "not_found",
    "details": "no rows in result set",
    "reference": "http://docs.iceye.com/constellation/api/specification/company/v1/#operation/GetContract"
}

This error format has the following fields:

Error field Description

title

A short, human-readable summary of the problem type, which generally matches the HTTP status code text.

code

A machine-readable error code.

details

A detailed description of the error, providing more context about the failure.

reference

A unique reference to the API documentation that helps to identify the error instance and can be used for further investigation or support.

Default format

If the API request does not have a HTTP Accept header that includes application/problem+json, the error response is returned in the following format:

{
    "code": "not_found",
    "message": "Error fetching contract"
}

This error format has the following fields:

Error field Description

code

A machine-readable error code.

message

A detailed description of the error.

Error conditions and semantics

The following error conditions might occur when invoking endpoints on the API.

400 - bad request

Indicates that the request sent by the user was malformed. This can be caused by:

  • Unknown parameter name (for example, incorrect spelling)

  • Required parameter is missing

  • Incorrect parameter values

Example error when the imaging mode was spelled with the wrong case:

{
    "code": "bad_request",
    "message": "request body has an error: Error at \"/imagingMode\" value is not one of the allowed values [\"SPOTLIGHT\",\"SPOTLIGHT_FINE\",\"SPOTLIGHT_FINE_1L\",\"SPOTLIGHT_FINE_2L\",\"SPOTLIGHT_FINE_3L\",\"SPOTLIGHT_EXTENDED_AREA\",\"SPOTLIGHT_EXTENDED_DWELL\",\"SPOTLIGHT_EXTENDED_DWELL_FINE\",\"SCAN\",\"SCAN_WIDE\",\"STRIPMAP\",\"SPOTLIGHT_HIGH_1L\",\"SPOTLIGHT_HIGH_2L\",\"SPOTLIGHT_PRECISE_1L\",\"SPOTLIGHT_PRECISE_2L\",\"SPOTLIGHT_PRECISE_3L\"]"
}

Verify the spelling and case of the parameter hinted in the error message.

Example error when PRIVATE exclusivity is not allowed by the contract:

{
    "code": "ERR_INVALID_EXCLUSIVITY",
    "message": "invalid model: invalid exclusivity: exclusivity \"PRIVATE\" is not allowed in contract"
}

Example error when a specific imaging mode is not allowed by the contract:

{
    "code": "ERR_UNAUTHORIZED_IMAGE_MODE",
    "message": "unauthorized model: unauthorized imaging mode: imaging mode \"spotlight_extended_dwell_fine\" is not allowed in contract"
}

Verify the parameter value and check if it is allowed in your contract.

Example error when the when the request was badly formed:

{
    "code": "bad_request",
    "message": "Bad Request"
}

Verify all the required parameters are provided and their spelling and case is correct.

403 - forbidden

Indicates that the request is not allowed.

For example, see Get task price.

404 - not found

Indicates that a required resource was not found.

For example, see Get summary and Get taskscene.

422 - unprocessable content

Indicates that the request could not be processed.

For example, see Create task.