Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

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

  • 400 invalid_request: a path, query or body parameter is missing, malformed or out of range.
  • 400 malformed_json: the request body isn’t valid JSON.
  • 400 invalid_api_version: the Doss-Version header isn’t a supported version.
  • 400 invalid_filter: the filter’s shape, operator or value isn’t valid for that field.
  • 400 invalid_sort: the sort names a field that can’t be sorted, or has more than three keys.
  • 400 invalid_cursor: the cursor is malformed or came from a different query.
  • 400 invalid_field: a field in fields, filter or sort doesn’t exist on the table or can’t be used there.
  • 401 unauthenticated: the API key is missing, malformed or revoked.
  • 403 api_not_enabled: API access isn’t enabled for your organization.
  • 404 not_found: the organization in the URL isn’t your key’s, or the path doesn’t exist.
  • 404 table_not_found: the table doesn’t exist or isn’t available to the API.
  • 404 record_not_found: the record doesn’t exist in that table.
  • 413 payload_too_large: the request body is too large.
  • 415 unsupported_media_type: the request body isn’t application/json.
  • 429 rate_limited: your key or organization sent too many requests; wait for Retry-After.
  • 500 internal_error: something went wrong on Doss’s side.
  • 503 service_unavailable: the API is temporarily unavailable.
  • 504 query_timeout: the query took too long; narrow the filter or use a smaller limit.

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

  1. 401 on every request: confirm the header is Authorization: Bearer <key> with no extra spaces or quotes, and that the key hasn’t been revoked.
  2. 403 api_not_enabled: your organization doesn’t have API access yet. A valid key isn’t enough on its own.
  3. 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.
  4. Fewer records than expected: check that you’re following next_cursor until has_more is false, and that your filters are correct.