> ## Documentation Index
> Fetch the complete documentation index at: https://docs.docinject.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DocInject API error codes and responses

> Every DocInject API error returns JSON with a detail field. Learn the HTTP status codes your integration should handle and how to parse error responses.

When a request fails, the DocInject API always returns a JSON body with a single `detail` field describing what went wrong. Your integration should read this field to surface actionable error messages.

## Error response format

Every error response follows this shape:

```json theme={null}
{
  "detail": "Document not found"
}
```

The `detail` value is a human-readable string. It changes with each error type, so treat it as display text rather than a stable key to match programmatically.

## HTTP status codes

| Status                       | Meaning                                                                                                                              |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `200 OK`                     | Request succeeded.                                                                                                                   |
| `201 Created`                | Resource was successfully created.                                                                                                   |
| `204 No Content`             | Request succeeded with no response body (for example, a delete operation).                                                           |
| `400 Bad Request`            | Invalid request body or missing required fields.                                                                                     |
| `401 Unauthorized`           | Missing or invalid `Authorization` header.                                                                                           |
| `403 Forbidden`              | You're authenticated but don't have permission to perform this action (for example, a non-admin attempting an admin-only operation). |
| `404 Not Found`              | The resource doesn't exist or you don't have access to it.                                                                           |
| `415 Unsupported Media Type` | Wrong file type (for example, a non-image file uploaded to an image endpoint).                                                       |
| `500 Internal Server Error`  | An unexpected server-side error occurred.                                                                                            |

<Note>
  **403 vs 404:** DocInject returns `404`, not `403`, for resources that exist but your token doesn't have access to. This prevents your integration from inferring whether a resource exists at all, which avoids leaking information across organization boundaries.
</Note>

## Handling errors in your integration

Check `res.ok` after every request and parse the `detail` field from the response body:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const res = await fetch('https://api.docinject.com/{org_slug}/inbox', {
    headers: { Authorization: `Bearer ${apiKey}` },
  });

  if (!res.ok) {
    const { detail } = await res.json();
    console.error('API error:', detail);
  }
  ```

  ```python Python theme={null}
  import os, requests

  res = requests.get(
      'https://api.docinject.com/{org_slug}/inbox',
      headers={'Authorization': f'Bearer {os.environ["DOCINJECT_API_KEY"]}'},
  )

  if not res.ok:
      detail = res.json().get('detail', 'Unknown error')
      print(f'API error ({res.status_code}): {detail}')
  ```
</CodeGroup>

## Common error scenarios

<AccordionGroup>
  <Accordion title="401, missing or invalid token">
    You'll receive a `401` when:

    * The `Authorization` header is absent
    * The header is present but not in `Bearer <token>` format
    * The token has been deleted or is otherwise invalid

    **Fix:** verify your API key is correct and that you're setting the `Authorization` header on the request.
  </Accordion>

  <Accordion title="403, insufficient permissions">
    You'll receive a `403` when your token is valid but the action requires a role you don't have. For example, only organization admins can invite members, change member roles, or view documents owned by other members.

    **Fix:** check that the API key belongs to a user with the required role, or contact your organization admin.
  </Accordion>

  <Accordion title="400, bad request">
    You'll receive a `400` when the request body is malformed or a required field is missing. The `detail` field will describe what's wrong, for example, `"count must be 1–100"`.

    **Fix:** validate your request payload against the endpoint's required fields before sending.
  </Accordion>

  <Accordion title="500, internal server error">
    A `500` indicates an unexpected error on DocInject's side. These are rare and usually transient.

    **Fix:** retry the request with exponential backoff. If the error persists, contact DocInject support with the request details and timestamp.
  </Accordion>
</AccordionGroup>

<Warning>
  Do not rely on the `detail` string value as a stable error code. Use the HTTP status code to branch your error handling logic.
</Warning>