Errors and troubleshooting
Error codes the Doss API returns, when to retry and how to fix common problems.
The Doss API uses standard HTTP status codes. Failed requests return a JSON error object per RFC 9457.
Error reference
400invalid_request: a path, query or body parameter is missing, malformed or out of range.400malformed_json: the request body isn’t valid JSON.400invalid_api_version: theDoss-Versionheader isn’t a supported version.400invalid_filter: the filter’s shape, operator or value isn’t valid for that field.400invalid_sort: the sort names a field that can’t be sorted, or has more than three keys.400invalid_cursor: the cursor is malformed or came from a different query.400invalid_field: a field infields,filterorsortdoesn’t exist on the table or can’t be used there.401unauthenticated: the API key is missing, malformed or revoked.403api_not_enabled: API access isn’t enabled for your organization.404not_found: the organization in the URL isn’t your key’s, or the path doesn’t exist.404table_not_found: the table doesn’t exist or isn’t available to the API.404record_not_found: the record doesn’t exist in that table.413payload_too_large: the request body is too large.415unsupported_media_type: the request body isn’tapplication/json.429rate_limited: your key or organization sent too many requests; wait forRetry-After.500internal_error: something went wrong on Doss’s side.503service_unavailable: the API is temporarily unavailable.504query_timeout: the query took too long; narrow the filter or use a smallerlimit.
Retrying requests
Retry only 429 and 5xx responses. Use exponential backoff with jitter (for example 1, 2, then 4 seconds, up to 5 attempts), and wait at least as long as Retry-After when it’s present. All Doss API requests are reads, so retrying them is always safe. See the response headers for exact API limits, see Rate limits.
Troubleshooting checklist
401on every request: confirm the header isAuthorization: Bearer <key>with no extra spaces or quotes, and that the key hasn’t been revoked.403 api_not_enabled: your organization doesn’t have API access yet. A valid key isn’t enough on its own.- A table or field is missing: field API names can differ from labels in the app. List tables and retrieve the table to confirm IDs and names.
- Fewer records than expected: check that you’re following
next_cursoruntilhas_moreisfalse, and that your filters are correct.