Response Codes

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

Sensos Standard Error Format

When an API request results in an HTTP 4xx or 5xx error, the response body contains a structured JSON error envelope:

{
  "error": {
    "id": "e5eba106-0faa-44cb-a8c7-38b2ebf45328",
    "code": "InvalidParameter",
    "message": "The specified accountId does not exist or is inaccessible.",
    "details": {
      "field": "accountId",
      "issue": "AccountNotFound"
    }
  }
}

Error Envelope Fields

Field Name	Type	Description
`error.id`	String (UUID)	Unique diagnostic tracking ID generated for the error instance. Include this ID when contacting Sensos support.
`error.code`	String	Machine-readable error discriminator (e.g. `InvalidParameter`, `DeviceNotExists`, `Unauthorized`, `RateLimitExceeded`).
`error.message`	String	Human-readable description of why the request failed and recommended remediation.
`error.details`	Object	Optional context-specific diagnostic details (e.g., offending field names or validation constraints).

HTTP Status Codes

2xx Success Codes

200 OK: The request was successful, and the server returned the requested representation.
201 Created: The resource was successfully created (typically returned by POST endpoints creating shipments, sets, or items). The response body contains the newly created entity and its unique ID.
202 Accepted: The request has been accepted for asynchronous batch processing (e.g. bulk set assignment or bulk retire). The response includes a Location header and body URL pointing to the status polling endpoint. See Long Running Operations.
204 No Content: The request succeeded, and no response body is returned (e.g. successful deletion or state transition).

4xx Client Error Codes

400 Bad Request: Malformed JSON syntax, invalid query parameters, or missing required fields in the request body. Review the error.message and error.details for validation specifics.
401 Unauthorized: Authentication failed. The Authorization: Bearer <token> header is missing, malformed, or the access token has expired. Re-authenticate via POST /v1/applications/token.
403 Forbidden: Authenticated credentials do not have permission to access the target tenantId or accountId. Verify your application role assignments in Sensos Sync.
404 Not Found: The requested resource (shipment, device, set, point of interest, or operation) does not exist under the specified accountId.
409 Conflict: The request could not be completed due to a resource state conflict (e.g. attempting to assign a device that is already actively linked to another ongoing shipment).
429 Too Many Requests: Rate limit exceeded. Sensos enforces rate limits to ensure platform stability.
- Remediation: Implement exponential backoff jitter and reduce request concurrency. Respect the Retry-After header if present.

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 error.id.
502 Bad Gateway: The gateway or proxy received an invalid response from an upstream microservice. 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:

The exact request URL and HTTP method.
The error.id tracking UUID returned in the response body.
The approximate UTC timestamp of the failed call.