Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.stigg.io/llms.txt

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

Every request to Stigg — whether it succeeds or fails — generates a trace ID. This ID is consistent across the activity log, the API response, and any webhook notifications emitted during the same request. You can use it to correlate all three signals into a single investigation, or share it with the Stigg team for server-side log correlation. There are three places where trace IDs surface:
  1. The activity log — for both successful and failed requests
  2. Error responses — on any failed API call
  3. Webhook error notifications — emitted when specific failure events occur

​
1. Activity log

Every event in the activity log carries a trace ID tied to the request that triggered it.

​
Viewing a trace ID for a successful request

  1. In the Stigg app, navigate to the relevant customer.
  2. Open the Activity tab.
  3. Click into the event (for example, subscription.created).
  4. The trace ID is shown in the event header.
From the same event view, you can also:
  • See the API request (the GraphQL mutation) that originated the event — this is exactly the request your application sent.
  • See the API response returned to your application for that request.
This makes the activity log useful not just for auditing what happened, but for confirming what your SDK or API client actually received.

​
Sharing an event with the Stigg team

Click Copy event link from the event header to get a direct URL to that event. You can share this link with the Stigg team to give them immediate context when requesting further investigation.

​
Filtering by trace ID

To find all events associated with a single request, use the Trace ID filter in the activity log. This is particularly useful when a single request triggers multiple downstream events (for example, a subscription creation that also triggers entitlement updates or billing sync events).

Activity log

​
2. Error responses

When a request fails, the Stigg API includes a trace ID in the error response. It appears in the extensions field of each error object: 
{
  "errors": [
    {
      "message": "Plan not found",
      "extensions": {
        "code": "PlanNotFound",
        "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
  ],
  "data": null
}

​
What to log on your side

When an error occurs, capture and log at minimum:
FieldWhere to find it
traceIderrors[].extensions.traceId
codeerrors[].extensions.code
messageerrors[].message
Operation nameThe GraphQL operation or REST endpoint you called
HTTP statusFrom the response headers

​
Using the trace ID

Once you have the trace ID from an error:
  • Search the activity log by trace ID to see whether Stigg recorded an event for the request and what state it left the system in.
  • Share it with the Stigg team to request a deeper investigation using Stigg’s internal logs.

​
Common error codes

CodeDescription
UnauthenticatedInvalid or missing API key
InvalidArgumentErrorThe request payload is malformed or contains invalid values
CustomerNotFoundThe referenced customer does not exist
SubscriptionNotFoundThe referenced subscription does not exist
PlanNotFoundThe referenced plan does not exist

​
3. Webhook error notifications

When a request fails, Stigg can emit a webhook notification in addition to returning an error response. These notifications carry the same trace ID as the originating request, so you can match them to the corresponding API call and activity log entry.

​
Available error events

subscription.create_failed — fired whenever a subscription creation attempt fails. 
{
  "type": "subscription.create_failed",
  "messageId": "a6ce...",
  "traceId": "549a...",
  "input": {
    "customerId": "customer-id",
    "planId": "plan-id",
    "billingPeriod": "MONTHLY",
    "startDate": "2022-08-21T21:45:29.617Z",
    "environmentId": "bf154237-4b89-4221-821e-dab51fe8c231"
  },
  "error": "Customer not found",
  "accountId": "ae3500ba-85da-4499-990c-1b9d24c13ccc",
  "environmentId": "bf154237-4b89-4221-821e-dab51fe8c231"
}
The input field contains the parameters that were sent in the original request. The error field contains the human-readable error message.
customer.payment_failed — fired when a charge attempt fails. Requires a billing provider integration (for example, Stripe or Zuora). 
{
  "type": "customer.payment_failed",
  "messageId": "a6ce...",
  "traceId": "549a...",
  "timestamp": "2022-08-24T14:11:54.525Z",
  "customer": {
    "id": "customer-test-id",
    "name": "customer-test",
    "email": "john@example.com"
  },
  "subscription": {
    "id": "subscription-plan-revvenu-essentials-0ecc92",
    "status": "PAYMENT_PENDING",
    "plan": { "id": "plan-revvenu-essentials", "name": "Essentials" }
  },
  "error": {
    "message": "Your card has insufficient funds.",
    "code": "card_declined",
    "details": "insufficient_funds"
  }
}
sync.failed — fired when Stigg fails to sync an entity to an integrated third-party system (for example, a CRM or billing provider). 
{
  "type": "sync.failed",
  "messageId": "a6ce...",
  "traceId": "549a...",
  "error": "Customer already exists",
  "id": "customer-id",
  "entityType": "CUSTOMER",
  "vendorIdentifier": "stripe"
}

​
Setting up error webhooks

To receive these notifications:
  1. Go to Settings > Integrations > Webhooks.
  2. Click + New webhook.
  3. Enter a service name and your endpoint URL.
  4. In Events to send, select the error events you want to subscribe to.
  5. Click Add.
Webhooks are activated immediately after creation. For full payload schemas and all available events, see:

Webhook events

​
Correlating across all three

The trace ID is the same across the API response, activity log, and webhook notification for a given request. For example, when a subscription creation fails:
  1. Your application receives an error response containing the trace ID.
  2. A subscription.create_failed webhook is emitted to your endpoint with the same trace ID.
  3. The activity log records the event, also tagged with that trace ID.
You can use this to:
  • Connect your application logs to the Stigg activity log.
  • Match webhook notifications to the specific request that caused them.
  • Correlate multiple downstream events triggered by one request.
To request a server-side investigation from Stigg, share the trace ID. It allows the Stigg team to look up the exact request in internal logs and provide detailed context on what occurred.