---
title: Errors and troubleshooting
description: >-
  Error codes the Doss API returns, when to retry and how to fix common
  problems.
sidebar:
  order: 2
---
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](/api/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.
1. **`403 api_not_enabled`:** your organization doesn't have API access yet. A valid key isn't enough on its own.
1. **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.
1. **Fewer records than expected:** check that you're following `next_cursor` until `has_more` is `false`, and that your filters are correct.
