Error Handling

All errors follow the same envelope format:

{
  "success": false,
  "error": {
    "type": "INSUFFICIENT_CREDITS",
    "message": "Your account has 0 credits remaining. This endpoint requires 1 credits.",
    "status": 402,
    "doc_url": "https://www.socialcrawl.dev/docs/errors/insufficient-credits"
  },
  "credits_remaining": 0,
  "request_id": "req-abc123"
}

Every response — success or error — includes an X-Request-Id header matching request_id. Include it when contacting support so we can trace the exact request in our logs.

Error Codes

Code	Status	Description	Action
`MISSING_API_KEY`	401	No `x-api-key` header on the request	Add the `x-api-key` header
`INVALID_API_KEY`	401	Key is malformed, not found, revoked, or expired	Check the key in Dashboard → API Keys
`INSUFFICIENT_CREDITS`	402	Balance is lower than the endpoint cost	Top up in Dashboard → Billing
`INVALID_REQUEST`	400	Missing required params, failed format validation, or no `oneOf` member satisfied	Check the endpoint's required parameters
`METHOD_NOT_ALLOWED`	405	Non-`GET` method against `/v1/*`. Response includes an `Allow: GET` header	Use `GET`
`ENDPOINT_NOT_FOUND`	404	Platform or resource is not supported	Check the API Reference
`RESOURCE_NOT_FOUND`	404	Upstream returned 404, or the resource exists but contains no usable data. Credits refunded when triggered by empty upstream	Verify the handle/URL exists
`IDEMPOTENCY_KEY_CONFLICT`	409	The `Idempotency-Key` you sent is already in use by another account	Generate a fresh key (UUIDv4 recommended)
`IDEMPOTENCY_KEY_PAYLOAD_MISMATCH`	422	You reused an `Idempotency-Key` with different query parameters	Use a new key for the new payload
`CONCURRENCY_LIMIT`	429	More than 50 concurrent requests on the same API key	Reduce concurrent requests
`UPSTREAM_ERROR`	502	Upstream platform returned an error. Credits refunded	Retry after a short backoff
`SERVICE_UNAVAILABLE`	503	Circuit breaker is open for this platform. Credits refunded. Response includes `Retry-After: 30`	Wait 30s and retry
`INTERNAL_ERROR`	500	Unexpected error. Credits refunded	Retry; contact support with the `request_id` if it persists

Refund Rules

Credits are automatically refunded when:

Upstream returns a 5xx error (UPSTREAM_ERROR, 502)
The circuit breaker rejects the request (SERVICE_UNAVAILABLE, 503)
An unexpected server error occurs (INTERNAL_ERROR, 500)
Upstream returns 200 with an empty body — e.g. a nonexistent handle — triggering RESOURCE_NOT_FOUND (404)

Credits are never deducted for these outcomes, so no refund is needed:

Cache hits (X-Cache: HIT, X-Credits-Used: 0)
METHOD_NOT_ALLOWED (405), IDEMPOTENCY_KEY_CONFLICT (409), and IDEMPOTENCY_KEY_PAYLOAD_MISMATCH (422)
Idempotent replays — the original charge already appears on your earlier request

Client errors (MISSING_API_KEY, INVALID_API_KEY, INVALID_REQUEST, ENDPOINT_NOT_FOUND) are rejected before any deduction.

Debugging Tips

Every error envelope carries a doc_url pointing at the per-code page at https://www.socialcrawl.dev/docs/errors/…
request_id matches the X-Request-Id header and the request_id column on Dashboard → Activity Logs
Persistent 502s on a known-good input usually indicate an upstream outage — check GET /v1/status for the platform's circuit state

Error Handling

Error Handling

Error Codes

Refund Rules

Debugging Tips

On this page