Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.catenatelematics.com/llms.txt

Use this file to discover all available pages before exploring further.

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

1

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.
2

Catena forwards to the TSP

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

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 StatusMeaning
200 OKThe TSP accepted the request. The resource was created or updated.
502 Bad GatewayThe TSP returned an error. Check the logs array for details.
The logs array contains one entry per attempt with:
FieldDescription
status"success" or "failed"
error_typeCategory of error: auth, validation, network, or tsp
error_detailsHuman-readable description of what went wrong, often including the TSP’s error message and HTTP status

​
When to Use Sync Mode

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.
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.
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.