Live App →
Developers

Errors

Status codes, error envelope shape, and recovery patterns.

For Developers

Errors

Sentinel returns structured error responses with actionable messages, never stack traces.

Error Envelope

{
  "status_code": 400,
  "error": "Validation Error",
  "detail": "The 'file' field is required for upload.",
  "code": "MISSING_REQUIRED_FIELD",
  "request_id": "req_abc123",
  "documentation_url": "https://sentinel-ai-platform.centricitywealth.tech/developers/errors/#missing_required_field"
}
Field Description
status_code HTTP status code
error Human-readable error category
detail Actionable message
code Machine-readable error code
request_id Unique ID for support tickets
documentation_url Link to detailed docs

Status Code Reference

400 Bad Request

| Code | Meaning | Fix | |——|———|—–| | MISSING_REQUIRED_FIELD | Required parameter missing | Check request body | | INVALID_FILE_TYPE | Unsupported format | Use PDF, JPG, PNG | | FILE_TOO_LARGE | >50MB | Compress or split document | | INVALID_DATE_RANGE | Start > end | Swap dates |

401 Unauthorized

| Code | Meaning | Fix | |——|———|—–| | TOKEN_EXPIRED | Access token expired | Refresh token | | INVALID_TOKEN | Malformed or revoked token | Re-authenticate | | MFA_REQUIRED | MFA not completed | Complete MFA flow |

403 Forbidden

| Code | Meaning | Fix | |——|———|—–| | INSUFFICIENT_PERMISSIONS | Role lacks access | Request role elevation | | TENANT_ISOLATION | Cross-tenant access attempted | Use correct tenant | | WRITE_DISABLED | Write operations disabled | Contact admin |

404 Not Found

| Code | Meaning | Fix | |——|———|—–| | DOCUMENT_NOT_FOUND | Document ID invalid | Check ID | | USER_NOT_FOUND | User ID invalid | Check ID | | ENDPOINT_NOT_FOUND | Wrong URL | Check API version |

409 Conflict

| Code | Meaning | Fix | |——|———|—–| | DUPLICATE_UPLOAD | Same file recently uploaded | Use deduplication hash | | CONCURRENT_MODIFICATION | Resource changed during edit | Retry with latest state |

422 Unprocessable Entity

| Code | Meaning | Fix | |——|———|—–| | EXTRACTION_FAILED | NLP pipeline error | Retry or contact support | | VALIDATION_ERROR | Business rule violated | Check constraints |

429 Too Many Requests

| Code | Meaning | Fix | |——|———|—–| | RATE_LIMIT_EXCEEDED | Quota exhausted | Wait and retry | | QUOTA_EXHAUSTED | Monthly quota reached | Contact sales |

500 Internal Server Error

| Code | Meaning | Fix | |——|———|—–| | INTERNAL_ERROR | Unexpected failure | Retry with backoff | | LLM_PROVIDER_ERROR | OpenAI/Bedrock outage | Retry or switch model | | DATABASE_ERROR | Postgres/Mongo issue | Retry with backoff |

Recovery Patterns

Exponential Backoff

import time
import random

def retry_with_backoff(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except SentinelAPIError as e:
            if e.status_code in (429, 500, 502, 503, 504) and attempt < max_retries - 1:
                delay = (2 ** attempt) + random.uniform(0, 1)
                time.sleep(delay)
            else:
                raise

Circuit Breaker

from circuitbreaker import circuit

@circuit(failure_threshold=5, recovery_timeout=60)
def call_sentinel_api():
    return client.upload_document("file.pdf")

Logging Best Practices

Always log:

  • request_id — for support tickets
  • status_code — for monitoring
  • code — for alerting rules
  • Timestamp and endpoint

Never log:

  • Access tokens
  • Refresh tokens
  • Document content
  • PII