Response Codes

When integrating with the Sensos REST API, understanding standard HTTP response codes and the Sensos error formats is essential for robust exception handling, retry logic, and troubleshooting.

Error Response Formats

The body of a 4xx or 5xx response depends on where the request was rejected. Check the status code first, then parse the body according to the shapes below.

Sensos Error Response

Errors raised while processing a valid request (for example, a business rule that is not met) return an ErrorResponse:

{
  "operationId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "errors": [
    {
      "message": "Device 860000000000001 is already retired",
      "deviceId": "860000000000001"
    }
  ]
}

Validation Problem Details

Requests that fail input validation (a missing required field, a value out of range, a malformed query parameter, an empty body) return 400 Bad Request with an RFC 7807 problem-details body. errors maps each invalid field to its messages:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00",
  "errors": {
    "name": [
      "The field name must be a string with a maximum length of 40."
    ]
  }
}

Problem Details

Some 404 Not Found responses (for example, getting a device, set, point of interest, carrier, or asset that does not exist) return an RFC 7807 problem-details body without an errors map:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Not Found",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}

A few Items validation errors return a plain-text message instead of JSON.

Gateway Errors

401 Unauthorized and 403 Forbidden are returned by the API gateway with an empty body. 429 Too Many Requests has a body that is not JSON.

HTTP Status Codes

2xx Success Codes

• 200 OK: The request was successful. Returned by reads, updates (PATCH/PUT), and actions such as closing or reopening a shipment and retiring or reactivating a device. Some actions return 200 with an empty body.
• 201 Created: The resource was successfully created (returned by POST endpoints that create shipments, sets, items, points of interest, assets, and data delivery rules). The Location header contains the new resource's ID; for assets, it contains the asset's path (/v1/accounts/{accountId}/assets/{assetId}).
• 202 Accepted: The request has been accepted for asynchronous processing. This is returned by bulk device retirement. The Location header and the location body field contain the absolute URL of the operation to poll. See Long Running Operations.
• 204 No Content: The request succeeded and no response body is returned. Returned only by DELETE endpoints.

4xx Client Error Codes

• 400 Bad Request: Malformed JSON syntax, invalid query parameters (including an invalid or expired pagination cursor), missing required fields in the request body, or a request that breaks a business rule. See the error formats above for details.
• 401 Unauthorized: Authentication failed. The Authorization: Bearer <token> header is missing, malformed, or the access token has expired. The body is empty. Re-authenticate via POST /v1/applications/token and retry once.
• 402 Payment Required: The request uses a feature that is not included in your plan (for example, ocean container or air waybill tracking identifiers on a shipment).
• 403 Forbidden: The body is empty. Returned when your application does not have access to the accountId in the URL (including an account that does not exist), when its role does not allow the operation, or when your tenant is inactive. Verify your application's account access and role in Sensos Sync.
• 404 Not Found: The requested resource (shipment, device, set, point of interest, asset, or operation) does not exist under the specified accountId.
• 412 Precondition Failed: The resource was updated by another request at the same time. Retry the request.
• 429 Too Many Requests: Rate limit exceeded. The API allows about 10 requests per second per IP address, with a small burst allowance.
  • Remediation: No Retry-After header is sent. Retry with exponential backoff and jitter, and reduce request concurrency.

5xx Server Error Codes

• 500 Internal Server Error: An unexpected server-side error occurred while processing the request. Retry with exponential backoff. If the issue persists, contact [email protected] with the operationId.
• 502 Bad Gateway: The gateway or proxy received an invalid response from an upstream service. Retry after a short delay.
• 503 Service Unavailable: The server is temporarily overloaded or undergoing maintenance. Retry after a short delay.
• 504 Gateway Timeout: Upstream processing exceeded the gateway timeout threshold. Retry with an exponential backoff schedule.

Support & Diagnostics

If an unexpected error occurs and cannot be resolved, please contact our engineering support team at [email protected]. Always include:

1. The exact request URL and HTTP method.
2. The operationId returned in the response body (or the traceId for problem-details responses).
3. The approximate UTC timestamp of the failed call.