Error codes
Every error.code value the API returns, with HTTP status, meaning, and recovery guidance
Every error response uses the standard envelope:
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "human-readable description",
"details": { /* optional structured detail */ }
}
}The code is the stable identifier you should branch on. The
message is for human display.
Authentication errors
| HTTP | error.code | Meaning | Recovery |
|---|---|---|---|
| 401 | UNAUTHORIZED | Missing or malformed Authorization header | Send Authorization: Bearer <key> |
| 401 | API_KEY_REVOKED | The key was revoked | Create a new key |
| 401 | API_KEY_EXPIRED | The key has expired | Create a new key |
| 401 | KEY_FORMAT_DEPRECATED | A legacy tb_* / ss_live_* key after the sunset window | Mint a new ss_secret_* or ss_org_* key in the dashboard |
| 403 | FORBIDDEN | Key lacks the permission for this endpoint | Use a key with the required permission |
| 403 | PUBLIC_KEY_REQUIRED | An ss_secret_* or ss_org_* key was used with the SDK | Use the ss_pub_* from Project → SDK Keys |
| 403 | SECRET_KEY_REQUIRED | An ss_pub_* key was used on a server-only endpoint | Mint an ss_secret_* (or ss_org_*) and use it server-side |
| 403 | ORG_KEY_REQUIRED | A project-scoped key was used on a tenant-only endpoint (e.g. POST /v1/projects) | Use an ss_org_* key |
| 403 | WRONG_PROJECT | X-Project-Id (or path id) doesn't match the key's project binding | Send the correct project id, or use an ss_org_* key |
| 403 | DASHBOARD_ONLY | This action lives in the dashboard | Sign in to the web app to perform it |
| 400 | MISSING_PROJECT_ID | ss_org_* key without X-Project-Id on a project-scoped endpoint | Send X-Project-Id |
| 400 | INVALID_PUBLIC_KEY_PERMISSIONS | Tried to mint an ss_pub_* with permissions outside analysis:create / analysis:read | Mint with the locked set, or pick ss_secret_* if you need broader access |
| 400 | CONFIRMATION_MISMATCH | DELETE /v1/projects/{id} body missing confirm field or it doesn't match the project slug | Set confirm to the project slug exactly |
Validation errors
| HTTP | error.code | Meaning | details shape |
|---|---|---|---|
| 400 | VALIDATION_ERROR | One or more fields failed schema validation | { issues: [{ path, message }] } |
| 400 | INVALID_TIME_RANGE | timeEnd is not after timeStart (or toDate not after fromDate) | — |
| 400 | INVALID_PROJECT_SLUG | Slug doesn't match ^[a-z0-9-]+$ | — |
Resource errors
| HTTP | error.code | Meaning |
|---|---|---|
| 404 | NOT_FOUND | The resource doesn't exist within your tenant scope |
| 409 | CONFLICT | A resource with the same unique field already exists (e.g. duplicate slug) |
| 409 | IDEMPOTENCY_KEY_CONFLICT | An Idempotency-Key was reused with a different request body — see Idempotency |
| 410 | GONE | The resource was deleted |
Quota and plan errors
| HTTP | error.code | Meaning | Recovery |
|---|---|---|---|
| 402 | PAYMENT_REQUIRED | Subscription is past due or trial expired | Resolve in Organization → Billing |
| 403 | QUOTA_EXCEEDED | Monthly analyses quota exhausted, overage not enabled | Enable overage or upgrade — see Overage |
| 403 | PLAN_FEATURE_GATE | Endpoint requires a higher plan tier | Upgrade — see Plans |
| 403 | RESOURCE_LIMIT | Per-resource limit reached (e.g. log sources per project) | Delete unused resources or upgrade |
Rate-limit errors
| HTTP | error.code | Meaning |
|---|---|---|
| 429 | RATE_LIMITED | Too many requests — see Rate limits for windows and headers |
Server-side errors
| HTTP | error.code | Meaning | Recovery |
|---|---|---|---|
| 500 | INTERNAL_ERROR | Unexpected server error | Retry with backoff; if persistent, email support@sigsentry.com with the requestId from the response |
| 500 | ANALYSIS_ERROR | An analysis failed during processing | Check the analysis detail for specifics; retry typically succeeds |
| 502 | UPSTREAM_ERROR | One of your connected integrations (a log source, repo provider, or notification channel) returned an error | The details.upstream field identifies the integration kind (e.g. log_source, repo, channel) so you can check the right place |
| 503 | SERVICE_UNAVAILABLE | Maintenance or partial outage | Retry with backoff |
| 504 | UPSTREAM_TIMEOUT | An upstream dependency timed out | Same as UPSTREAM_ERROR |
Idempotent retries
5xx, 429, and UPSTREAM_ERROR (502) are safe to retry. Use
exponential backoff with jitter, and cap your retry budget so a
persistent failure doesn't loop forever.
4xx (other than 429) are client errors and won't succeed on retry
without a request change.
Request id
Every error response includes a requestId field for support:
{
"success": false,
"error": { "code": "INTERNAL_ERROR", "message": "...", "requestId": "req_..." }
}Include the requestId when contacting support.