Errors & Status Codes

The SignalStack API uses conventional HTTP status codes and returns structured JSON error responses for every non-2xx response. Always check the error.code field for machine-readable handling.

Error response format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The 'claim' field must be between 1 and 2000 characters.",
    "details": {
      "field": "claim",
      "constraint": "length",
      "max": 2000
    },
    "docs": "https://signal-stack-ten.vercel.app/docs/api-reference/verify-claim",
    "request_id": "vrf_a1b2c3d4e5f6"
  }
}

Field	Type	Description
`error.code`	string	Machine-readable error code for programmatic handling
`error.message`	string	Human-readable description of the error
`error.details`	object	Additional context (field name, constraints, etc.)
`error.docs`	string	Link to relevant documentation
`error.request_id`	string	Unique identifier for debugging with support

Error code reference

HTTP Status	Error Code	Message	Common Cause
400	`INVALID_REQUEST`	Malformed request body or missing required fields	Invalid JSON, wrong Content-Type, missing parameter
401	`UNAUTHORIZED`	Missing or invalid API key	No Authorization header, revoked key, malformed token
403	`FORBIDDEN`	API key lacks permission for this endpoint	Starter key used for verify/media
402	`INSUFFICIENT_CREDITS`	Account has insufficient credits	Monthly quota exhausted
404	`NOT_FOUND`	Endpoint or resource not found	Wrong URL, invalid version
413	`CONTENT_TOO_LARGE`	Request content exceeds maximum size	File > 50 MB, claim > 2000 chars
409	`CONFLICT`	Request conflicts with current state	Idempotency key reuse with different params
422	`VALIDATION_ERROR`	Request body fails validation	Invalid URL format, unsupported source, bad enum
429	`RATE_LIMITED`	Rate limit exceeded	Too many requests in window
500	`INTERNAL_ERROR`	Unexpected server error	Temporary internal failure
502	`UPSTREAM_ERROR`	Upstream data source unavailable	Data source timeout or error
503	`SERVICE_UNAVAILABLE`	Temporary service disruption	Planned maintenance or incident

HTTP status code summary

Status	Category	Retry?	Description
2xx	Success	—	Request succeeded
4xx	Client error	Only 429	Fix the request before retrying
5xx	Server error	Yes	Temporary issue, retry with backoff

Validation error details

When a 422 VALIDATION_ERROR is returned, the details object may contain afields array pinpointing each validation failure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "fields": [
        {
          "field": "sources.0",
          "message": "Unsupported source 'twitter'. Valid values: web, wikipedia, google_fact_check, semantic_scholar, gdelt"
        },
        {
          "field": "claim",
          "message": "Claim must not exceed 2000 characters (current: 2451)"
        }
      ]
    },
    "request_id": "vrf_z9y8x7w6v5u4"
  }
}

Idempotency

To safely retry requests, provide an Idempotency-Key header with a UUID. If a request is retried with the same key within 24 hours and the same request body, the API returns the original response (including cached results). This is safe for all POST endpoints.

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Next steps

Review Error Handling guide for retry strategies
Check Rate Limits
Browse SDKs for built-in error handling