Monitoring

The Talent API serves the fictional sandbox and three live account/license reads. Log request IDs, error codes, rate-limit headers and client timings for the supported endpoints. The webhook, session, usage and revocation workflows below are production planning guidance; they are not available monitoring features of the current sandbox. Start with the quickstart. For a future live integration, successful checks alone will not establish health: escalations, held outputs and revocations also need deadline monitoring.

Log request IDs

Every response carries a Request-Id header, such as req_8f2k4m6p8r0t2v4x6z8b0d2f4h. Every error body carries the same value as request_id.

{
  "type": "https://docs.reflections.ai/errors/rate_limited",
  "title": "Too many requests",
  "status": 429,
  "code": "rate_limited",
  "request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}

Log it with every call, next to the object IDs involved (chk_…, gen_…, ses_…, rvk_…) and your own job ID. When you contact support, the request ID is the fastest way to find what happened. Log the code of every error, not only the HTTP status: a 409 can mean anything from idempotency_key_in_use to session_not_active. Do not log secret keys, webhook secrets or whole tokens, and keep prompt text out of shared logs.

What to measure

Use the rows that match supported endpoints today. Rows for unserved capabilities are targets for a future integration; their dashboard views and background processing are not available yet.

Measure	Why it matters	Source
Decisions by `decision` and `reasons[].code`	A jump in one reason usually means a pipeline change, such as a new rewrite step adding text	Check responses
Escalated checks still open, and the oldest	Users waiting; escalations expire after 7 days	Your job store, or `GET /v1/checks?status=escalated`
Held generations, and the oldest	Held outputs expire after 7 days	`GET /v1/generations?status=held`
Generations by `status`, and time to decision	Asynchronous checks running late, or outputs delivered without one	Generation responses and events
Revocations by `status`, and which required actions are unacknowledged	An action other than `withdraw_outputs` near `acknowledge_by`, or `withdraw_outputs` near `post_revocation.withdraw_by`, is about to go overdue	`GET /v1/revocations?status=pending_acknowledgement`
Webhook delivery failures	Planned policy: disable a continuously failing endpoint after 5 days	Planned delivery records, and your endpoint’s own logs
Errors by `code`	`artifact_digest_mismatch`, `generation_already_submitted` and `idempotency_key_reused` point at bugs; `503` and timeouts at availability	Error bodies
Rate limit headroom	Running near the limit turns traffic peaks into `429`s	`RateLimit` and `RateLimit-Policy` headers
Latency per endpoint	Record your measured baseline; the proposed p95 targets of 150 to 500 ms for checks and 2 s for image generations are not verified service guarantees	Your client timings
Session terminations by `termination.reason`	Denied samples or revocations cutting calls	Session events
Rejected usage records by `rejection.code`	Under-reporting shows on statements	Usage record responses

Alerts

These are proposed operational alerts for the full API. The sandbox does not deliver the named webhook events or run the background deadline workflows.

Condition	Severity	What to do
A required action other than `withdraw_outputs` is unacknowledged an hour after `effective_at`	Page	Find the step that stalled and finish it. The deadline is `acknowledge_by`, 24 hours after `effective_at`.
`withdraw_outputs` is unacknowledged halfway from `effective_at` to `post_revocation.withdraw_by`	Page	Finish taking released outputs down, then acknowledge `withdraw_outputs`.
`revocation.overdue`	Page	Acknowledge the late actions now: those due by `acknowledge_by` if it passed, or `withdraw_outputs` if `withdraw_by` passed. It is shown as overdue on the talent’s record.
`license.suspended`	Ticket	Confirm that cached decisions under the license were dropped. A suspension is not a revocation: there is nothing to acknowledge.
`webhook_endpoint.disabled`	Page	Fix the endpoint, re-enable it, and replay missed events.
Webhook deliveries failing for more than an hour	Page	Your revocation feed polling is now the only path. Check it is running.
`503 service_unavailable` above your normal rate	Page	Check status.reflections.ai. Named-talent generation is failing closed.
Revocation feed not read for more than 2 minutes	Page	Your cached decisions are no longer safe to serve.
Escalations older than 3 days	Ticket	Tell the affected users, or cancel what they no longer need.
Rejected usage records	Ticket	Correct them with `correction_of`.

Revocations

Revocations carry hard deadlines on your side: acknowledge_by for every required action except withdraw_outputs, and post_revocation.withdraw_by for withdraw_outputs. Watch them three ways:

The revocation.created handler records each revocation and when it was received.
Your feed reader records each GET /v1/revocations?after=… call and the cursor it reached, and alerts when it stops running.
A scheduled job lists status=pending_acknowledgement and status=overdue, alerts at once on any overdue revocation, and compares each pending revocation’s acknowledgements with its required_actions. It alerts on each deadline separately: actions other than withdraw_outputs still unacknowledged long before acknowledge_by, and withdraw_outputs still unacknowledged long before post_revocation.withdraw_by. A revocation that requires withdraw_outputs stays pending_acknowledgement after your first call, so that status alone is not a fault.

Webhook health

Hosted webhook delivery is not available in the current sandbox. The proposed production policy is to retry a failed delivery with exponential backoff for 72 hours: after about 5 seconds, 1 minute, 5 minutes, 30 minutes, 2 hours and 5 hours, then every 10 hours. An endpoint that fails every delivery for 5 days would be disabled, and webhook_endpoint.disabled would go to your other endpoints and your account email. The planned recovery flow after an outage is to read missed events with GET /v1/events and after set to the last event you processed, or resend single events with POST /v1/events/{event_id}/resend. Events are kept for 30 days under the proposed policy. These event endpoints are not served by the current sandbox.

Status page

status.reflections.ai provides the published service status. Link it from your runbook and check which components it covers. It does not replace testing the Talent API journey your integration uses. The 99.95% monthly availability figure and latency figures in the API design are proposed targets, not a verified SLA for the sandbox. Incident subscriptions and response commitments must be confirmed before relying on them.

Exercise alerts for supported sandbox errors now. Rehearse revocation deadlines and webhook delivery failures when those capabilities become available; the current sandbox cannot perform those rehearsals.

Errors

The problem-details format and every error code.

Rate limits

Limits, headers and raising them.

Handle revocations

The feed, purges and acknowledgements.

Support

How to reach Reflections and what to send.

Get started

Quickstarts

Concepts

Integration guides

Build

Go to production

Log request IDs

What to measure

Alerts

Revocations

Webhook health

Status page

Errors

Rate limits

Handle revocations

Support

​Log request IDs

​What to measure

​Alerts

​Revocations

​Webhook health

​Status page

​Related

Errors

Rate limits

Handle revocations

Support

Log request IDs

What to measure

Alerts

Revocations

Webhook health

Status page

Related