DEVELOPER GUIDE
Errors & troubleshooting
Diagnose authentication, access and rate-limit responses.
Errors and refusals
Application JSON errors return error.code, error.message, error.reason.category, error.reason.retryable, requestId and meta; details can appear in error.reason.details. Proxy and transport failures may not return this JSON shape. Domain refusals are successful records that identify the unresolved concept, reason, evidence, hash, and source locator. Clients must not convert missing or refused values to zero.
Troubleshooting your first request
| What you see | What to check |
|---|---|
| 401: authentication required or invalid credential | Check that the server environment contains a current, non-revoked API key and sends the Bearer header. For browser pages, sign in again. Never paste a key into support messages. |
| 403: insufficient permission or resource outside plan | Check required scopes, organization role, company access and any provider retrieval window. A browser-session-only route requires the signed-in website, not a broader API key. Repeating the same request will not fix permissions. |
| 429: rate or monthly quota limit | Read the error code and retry metadata. Back off for a short-term rate limit; for a monthly allowance, wait for its reset or change your plan. Check Usage. There are no automatic overage charges. |
Invalid filters or invalid_cursor | Use the operation's allowed fields, enums and limits; keep start dates before end dates and minimum values no greater than maximum values. Do not reuse a cursor after changing filters. If the collection snapshot changed, restart from the first page and deduplicate previously processed records. |
query_cost_exceeded | Reduce the requested limit or query complexity. Check the query-cost formula and response limits instead of retrying unchanged. |
| 200 with no matching results, or unavailable values | The request succeeded. Check ticker, dates, forms, evidence-status filters, account access and indexed coverage. Metadata discovery is not passage extraction. Narrowing or broadening filters cannot create absent evidence; never substitute zero for missing values. |
| Timeout, network error or 5xx | Check connectivity and retain the request ID. Retry bounded read operations with backoff only when appropriate. Do not blindly retry a mutation: confirm whether it succeeded first. |
Support
For account, sales, or integration help, use the FilingSift contact form or email support@filingsift.com. Include the request ID when asking about an API error; never send passwords, session tokens, or API keys.