Error reporting

Connected apps can send crash and API failure reports to PortModels so the developer can see what went wrong for the app's users. Reporting is opt-in: the app must request the errors.report Connect scope, and the user must grant it.

Send a report#

Send the report to the API with the connected user's access token:

curl https://api.portmodels.com/errors/report \
  -H "Authorization: Bearer pmc_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "checkout-8f42",
    "kind": "api_error",
    "message": "The checkout request failed",
    "failed_action": "checkout.submit",
    "request_id": "req_123",
    "app_version": "2.4.1",
    "environment": "production",
    "error_code": "CHECKOUT_TIMEOUT",
    "http_status": 504,
    "context": {"operation": "checkout.submit"}
  }'

event_id, kind, and message are required. kind is either app_error or api_error. Stack traces are accepted for debugging, but request and response bodies, cookies, authorization headers, and arbitrary context are not accepted. URLs are stored without credentials, query strings, or fragments. Sensitive token-like values are redacted before storage.

The response is 201 when the report is stored and 200 when the same event_id has already been accepted for that user and app. A 401 means the token is missing, expired, or revoked; a 403 means the reporting scope was not granted or reporting is paused; a 413 means the bounded payload is too large; and a 429 means a quota was reached. On 429, wait for the number of seconds in Retry-After before trying again.

The JavaScript SDK exposes the same endpoint as client.errors.report():

await client.errors.report({
  eventId: "checkout-8f42",
  kind: "api_error",
  message: "The checkout request failed",
  failedAction: "checkout.submit",
  errorCode: "CHECKOUT_TIMEOUT",
  httpStatus: 504,
});

What developers see#

The app owner sees grouped issues, occurrence counts, affected-user counts, recent versions, and a small set of unexpired samples in the app's Errors panel. PortModels administrators can review reports across apps. Reports are kept for seven days from server receipt and then removed.

Reporting is best effort. The app should never block a user action on the diagnostic request, should suppress identical local failures, and should stop retrying while a 429 cooldown is active.