Debugging with a trace ID: everything that happened to a request

When something goes wrong, you don't need to send us screenshots or rebuild from your own logs what you sent. Every call to the Calisero API gets a unique trace ID, and with it you have access to everything recorded for that call: the exact request, the exact response, the timings, the messages created, the delivery and the callbacks sent to your server.

Where to find the trace ID

• in the X-Trace-Id header of every API response, success or error;
• in the body of every error response, in the trace_id field;
• in the dashboard, on the page of every API log, every message and every callback.

An error response looks like this:

{
  "message": "The sender is invalid or is not approved.",
  "errors": {
    "sender": ["The sender is invalid or is not approved."]
  },
  "trace_id": "9b80eef1-49d4-4502-85a8-febb68cc11a7"
}

Our advice: write the trace ID into your application's logs, next to every call. When a customer tells you an SMS never arrived, you know right away where to start.

Follow the whole flow

In the dashboard, under Developers → Debug, paste the trace ID and you see the request's whole story, in the order it happened. It also works with the ID of a message, an OTP verification, a callback or an API log: you are shown the request it belongs to.

The page has two parts:

• At a glance — the request's stages, each with its state and time: the API request, the messages created, the delivery (delivered, failed, in progress) and the callbacks;
• Everything recorded — every record in time order, linked to its full detail.

You see everything

From Debug you open any record and see its full detail:

• The API request — the method, the endpoint, the body you sent exactly as it reached us, the API key used, the user agent and the time;
• The API response — the HTTP code, the response body and, for validation errors, the field at fault and why;
• The timings — the duration of every API call and every callback, plus the time of each stage: created, sent, delivered, called back;
• The message — the recipient, the text, the sender, the number of parts, the status and its history;
• The callbacks — the URL called, the payload sent, the code and body your server answered with, the duration and, when the call failed, the connection error;
• the cURL command — for an API request, ready to run in a terminal, to replay the exact call.

Sensitive data (the API key, passwords) is masked in the logs.

How to debug, step by step

1. Get the trace ID from the response or from your logs.
2. Open it in Debug. Look at At a glance: the stage marked in red tells you where the request stopped.
3. Was the request refused (4xx)? Open the API log: the response says which field is wrong and why. Compare the body you sent with what you thought you sent — most of the time the difference is right there.
4. The message was created but not delivered? Open the message: its status and error code tell you why. See also the guide to failed deliveries.
5. The callback never reached you? Open the callback: you see what your server answered (code, body, duration) or why it could not connect.
6. Fixed it? Copy the cURL command, adjust it and replay the call. The new response has its own trace ID.

When you contact support

Send us the trace ID. It is all we need to find the request, with no personal data and no guesswork.

How long it is kept

Request and callback logs are kept for a limited number of days — the Debug page tells you how many. Messages stay.