Error handling

This page describes how errors are communicated by the CAS API, covering both synchronous (immediate) and asynchronous (via notifications) error handling.

Content types

The CAS API supports both JSON and XML. Use the Content-Type header to specify the format of your request body:

Content-Type	Format
`application/json`	JSON (default)
`application/xml`	XML

Use the Accept header to control the format of the response. If not specified, the API defaults to JSON.

Sending a request with an unsupported Content-Type returns 415 Unsupported Media Type.

HTTP status codes

Status	Meaning	Action
200 OK	Successful retrieval	Process the response body
201 Created	Resource created	Store the returned ID or reference
202 Accepted	Accepted for asynchronous processing	Does not mean success — await the processing result via Notifications
204 No Content	Successful deletion	No response body
307 Temporary Redirect	Attachment download redirect	Follow the redirect URL (most HTTP clients do this automatically)
400 Bad Request	Structural or format validation failed	Inspect the RFC 7807 error body and fix the indicated fields
401 Unauthorized	Token is missing, expired, or invalid	Re-authenticate — see Authentication
403 Forbidden	Valid token but insufficient scopes or tenant mismatch	Check your token's scopes and tenant ID
404 Not Found	Requested resource does not exist	Verify the resource ID
415 Unsupported Media Type	Incorrect `Content-Type` header	Use `application/json` or `application/xml`
429 Too Many Requests	Rate limit exceeded	Wait and retry with exponential backoff
500 Internal Server Error	Unexpected server-side error	Retry with backoff; contact support if persistent
502 Bad Gateway	Upstream service error	Retry with backoff
503 Service Unavailable	Service temporarily unavailable (e.g. maintenance)	Retry later

Synchronous error responses (400 Bad Request)

Validation errors on request structure and format are returned immediately as an RFC 7807 Problem Details response:

Not all endpoints return errors in the exact RFC 7807 format shown below. Some endpoints may use a slightly different error structure. The example below shows the most common format.

{
    "type": "Validation violation",
    "status": 400,
    "title": "One or more validation errors occurred.",
    "detail": "Your request parameters didn't validate.",
    "instance": "/v1/customsshipments",
    "invalid-parameters": [
        {
            "name": "ExternalReference",
            "reason": "'External Reference' must not be empty."
        },
        {
            "name": "Direction",
            "reason": "'Direction' must not be empty."
        }
    ]
}

Field	Description
type	Category of the error
status	HTTP status code (always 400 for validation errors)
title	Short human-readable summary
detail	Longer human-readable explanation
instance	The request path that generated the error
invalid-parameters	Array of specific field validation failures, each with `name` (field name) and `reason` (validation message)

Asynchronous error handling

Most ingestion and action endpoints return 202 Accepted, which means the message has been accepted for background processing. A 202 does not confirm that business validation has passed or that the operation succeeded.

Asynchronous results are communicated through two mechanisms:

1. Notification webhooks

Subscribe to the relevant events to receive processing outcomes:

Event Type	Subtype	Meaning
`CustomsShipmentInformation`	`CreationUnsuccessful`	Customs shipment creation failed business validation
`CustomsShipmentInformation`	`ReplaceUnsuccessful`	Customs shipment replacement failed
`CustomsShipmentInformation`	`ReplaceSuccessful`	Customs shipment replacement succeeded
`DeclarationActionFinished`	`HeaderUpdateUnsuccessful`	Declaration header update failed
`DeclarationStatusChanged`	`Invalid`	Declaration failed CAS validation
`DeclarationStatusChanged`	`CustomsError`	Declaration was rejected by customs
`DeclarationActionFinished`	(various)	Result of a declaration action (submit, invalidate, amend, etc.)

See Notification events for the complete list and payload structures.

2. Declaration error details

When a declaration is in Invalid or CustomsError status, retrieve the specific errors using the declaration GET endpoint with the include=errors parameter:

GET /v1/declarations/{declarationId}?include=errors

The response includes an errors array:

{
    "errors": [
        {
            "errorCode": "V0010",
            "message": "Invalid additional declaration type",
            "description": "SingleAdministrativeDocument.AddDeclType must be of type 'D'",
            "fieldReference": [
                {
                    "fieldName": "AddDeclType1",
                    "path": "SingleAdministrativeDocument"
                }
            ]
        }
    ]
}

Error codes prefixed with V (e.g., V0010) are CAS internal validation errors. Errors returned by customs systems use the error codes defined by the respective customs authority.

Correlating async results

When you send data to an ingestion endpoint, the 202 Accepted response includes a referenceId. This same reference appears in creation and replace notification events (e.g. CreationUnsuccessful, ReplaceSuccessful) under the ingestionReferences field, allowing you to correlate the processing result back to your original request. Note that downstream events such as DeclarationStatusChanged do not include ingestionReferences; use the customsShipmentReference on those events to track declaration progress.

← Previous Page