Sync Write Operations | Catena Telematics API

Synchronous mode couples your API call directly to the TSP’s response. When you submit a request with is_sync=true, Catena forwards it to the TSP, waits for the response, and returns the result directly to you — all in a single HTTP round-trip.

Best for development and debugging. Sync mode lets you see TSP responses immediately, making it easy to iterate on payloads and troubleshoot field requirements across different providers.

How It Works

You submit a write request with is_sync=true

Send a POST or PATCH request to the Telematics API with the is_sync=true query parameter.

Catena forwards to the TSP

The request is translated and forwarded to the TSP immediately — no queuing, no background processing.

You receive the TSP result directly

The response contains the complete resource operation, including the TSP’s response data, error details, or the created resource’s IDs.

Sync mode does not include automatic retries or rate limiting. If the TSP is temporarily unavailable or rate-limited, the error is returned directly to you and it’s your responsibility to retry.

Example: Sending a Message (Success)

Request

cURL

curl -X POST 'https://api.catenatelematics.com/v2/telematics/messages?is_sync=true' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "connection_id": "019ddd87-eedd-710f-967c-1c6cc72ac985",
    "sender_id": "f9c7ee1c-2e16-5858-9b7e-ff7c89a4dd04",
    "recipient_id": "b224f322-b3d2-57e0-b245-cda313f68a1d",
    "message_text": "Delivery confirmed at warehouse B",
    "priority": "low"
  }'

Response (200 OK)

On success, the response contains the completed resource operation with resource_id and source_id populated:

{
  "id": "019df230-a1b2-7890-cdef-1234567890ab",
  "created_at": "2026-05-04T09:15:00.000000Z",
  "updated_at": "2026-05-04T09:15:01.500000Z",
  "deleted_at": null,
  "partner_id": "9df92c50-d8a7-460e-aab2-a93f1de9280a",
  "connection_id": "019ddd87-eedd-710f-967c-1c6cc72ac985",
  "resource": "message",
  "resource_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "source_id": "98765432",
  "operation_type": "create",
  "payload": {
    "priority": "low",
    "sender_id": "f9c7ee1c-2e16-5858-9b7e-ff7c89a4dd04",
    "message_text": "Delivery confirmed at warehouse B",
    "recipient_id": "b224f322-b3d2-57e0-b245-cda313f68a1d",
    "connection_id": "019ddd87-eedd-710f-967c-1c6cc72ac985",
    "source_sender_id": "51477344",
    "reply_to_message_id": null,
    "source_recipient_id": "51477717",
    "source_reply_to_message_id": null
  },
  "status": "success",
  "logs": []
}

Key differences from the async response:

status is "success" (not "pending")
resource_id contains the Catena ID of the newly created resource
source_id contains the TSP-side ID of the newly created resource

Example: Sending a Message (Failure)

When the TSP returns an error, Catena returns a 502 Bad Gateway response because it acts as a gateway to the TSP and the error originated upstream.

Response (502 Bad Gateway)

{
  "id": "019df22e-f255-7a7c-b1d7-59f509071b6d",
  "created_at": "2026-05-04T08:51:01.487639Z",
  "updated_at": "2026-05-04T08:51:02.179210Z",
  "deleted_at": null,
  "partner_id": "9df92c50-d8a7-460e-aab2-a93f1de9280a",
  "connection_id": "019ddd87-eedd-710f-967c-1c6cc72ac985",
  "resource": "message",
  "resource_id": null,
  "source_id": null,
  "operation_type": "create",
  "payload": {
    "priority": "low",
    "sender_id": "f9c7ee1c-2e16-5858-9b7e-ff7c89a4dd04",
    "message_text": "Delivery confirmed at warehouse B",
    "recipient_id": "b224f322-b3d2-57e0-b245-cda313f68a1d",
    "connection_id": "019ddd87-eedd-710f-967c-1c6cc72ac985",
    "source_sender_id": "51477344",
    "reply_to_message_id": null,
    "source_recipient_id": "51477717",
    "source_reply_to_message_id": null
  },
  "status": "failed",
  "logs": [
    {
      "id": "019df22f-093f-7949-908d-d5564941fdbe",
      "created_at": "2026-05-04T08:51:02.079501Z",
      "updated_at": "2026-05-04T08:51:02.079501Z",
      "resource_operation_id": "019df22e-f255-7a7c-b1d7-59f509071b6d",
      "status": "failed",
      "error_type": "auth",
      "error_details": "Client error '401 Unauthorized' for url 'https://api.samsara.com/v1/fleet/messages'\nFor more information check: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401"
    }
  ]
}

When a sync operation fails, resource_id and source_id are both null because the resource was never created on the TSP.

Understanding Error Responses

HTTP Status	Meaning
`200 OK`	The TSP accepted the request. The resource was created or updated.
`502 Bad Gateway`	The TSP returned an error. Check the `logs` array for details.

The logs array contains one entry per attempt with:

Field	Description
`status`	`"success"` or `"failed"`
`error_type`	Category of error: `auth`, `validation`, `network`, or `tsp`
`error_details`	Human-readable description of what went wrong, often including the TSP’s error message and HTTP status

When to Use Sync Mode

Building and debugging integrations

When you’re first integrating write operations, sync mode lets you see TSP errors immediately. Different TSPs have different field requirements — sync mode helps you iterate quickly on your payload structure.

Interactive user workflows

When your end user needs immediate confirmation that a resource was created. For example, a dispatcher sending a message who needs to see “Message sent” or an error right away.

Operations requiring the TSP response

When you need the TSP-assigned resource ID (source_id) or other response data immediately to continue your workflow.

Recommended development workflow: Start with is_sync=true while building your integration to quickly identify and fix payload issues. Once your payloads are stable, switch to async mode (is_sync=false) for production to benefit from automatic retries and rate limiting.

Sync vs Async: Choosing the Right Mode

Next Steps

Async Operations

Learn about async mode with automatic retries and webhook tracking.

Webhook Setup

Configure webhooks to track resource operation outcomes.