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

# Errors

> Understand our error responses and debug failed requests.

export const httpStatusTableColumns = [{
  "key": "status",
  "header": "Status",
  render: value => <code className="font-mono text-[13px] font-regular">{value}</code>
}, {
  "key": "description",
  "header": "Description"
}];

export const httpStatuses = [{
  status: "200",
  description: "Everything worked as expected."
}, {
  status: "201",
  description: "Everything worked as expected and a new resource was created. This is typically used for create operations (POST requests)."
}, {
  status: "202",
  description: "The request has been accepted for processing, but the processing has not been completed. This is used for asynchronous operations."
}, {
  status: "400",
  description: "The request was unacceptable, often due to a validation error."
}, {
  status: "401",
  description: "No valid credentials provided."
}, {
  status: "403",
  description: "The provided credentials don't have permissions to perform the request."
}, {
  status: "404",
  description: "The requested resource doesn't exist."
}, {
  status: "409",
  description: "The request conflicts with the current state of the resource."
}, {
  status: "500",
  description: "Something went wrong on our end."
}];

export const Table = ({columns, data, rowKey, title}) => {
  const keyField = rowKey || columns[0]?.key;
  const getColWidth = (col, index) => {
    if (col.width) return col.width;
    return index === 0 ? "auto" : "minmax(0, 1fr)";
  };
  const gridTemplate = columns.map(getColWidth).join(" ");
  return <div className="w-full text-sm border border-gray-200 rounded-lg overflow-hidden" style={{
    display: "grid",
    gridTemplateColumns: gridTemplate
  }}>
      {}
      {title && <div className="py-3 px-4 font-semibold text-md text-gray-700 border-b border-gray-200" style={{
    gridColumn: "1 / -1"
  }}>
          {title}
        </div>}
      {}
      {columns.map(col => <div key={`header-${col.key}`} className="py-3 px-4 font-semibold text-[12px] text-gray-600 uppercase whitespace-nowrap bg-gray-50 border-b border-gray-200">
          {col.header}
        </div>)}
      {}
      {data.map((row, rowIndex) => columns.map((col, colIndex) => <div key={`${row[keyField]}-${col.key}`} id={colIndex === 0 ? row[keyField] : undefined} className={`py-3 px-4 text-gray-600 leading-relaxed border-b border-gray-100 ${colIndex === 0 ? "whitespace-nowrap" : ""} ${rowIndex % 2 === 0 ? "bg-white" : "bg-gray-50"}`}>
            {col.render ? col.render(row[col.key]) : row[col.key]}
          </div>))}
    </div>;
};

The API uses HTTP status codes to indicate the success or failure of a request. Status codes
in the `200-299` range indicate success, codes in the `400-499` range indicate a client
error (e.g failed validation) and should be fixed and retried in your end, and codes in
the `500-599` range indicate a server error on our end. Status codes in the `300-399` range
indicate a redirect. Some endpoints are [idempotent](/api-reference/idempotency) and so are safe to retry.

## Error response

<ResponseField name="code" type="string" required>
  A machine-readable <Link href="/api-reference/error-codes">error code</Link> that can be used to programmatically handle the error.
</ResponseField>

<ResponseField name="detail" type="string" required>
  A developer-facing description of the error. This description is not meant to be
  displayed to the user.
</ResponseField>

<ResponseField name="docs" type="string">
  A URL to the error documentation page.
</ResponseField>

<ResponseField name="params" type="array">
  An array of objects describing the parameters that caused the error. This is mostly
  present for validation errors (HTTP 400).

  <Expandable title="properties">
    <ResponseField name="path" type="string" required>
      The path to the parameter that caused the error.
    </ResponseField>

    <ResponseField name="detail" type="string" required>
      A developer-facing description of the error. This description is not meant to be
      displayed to the user.
    </ResponseField>

    <ResponseField name="code" type="string" required>
      A machine-readable error code that can be used to programmatically handle the error.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="context" type="object">
  A context object that provides additional information about the error. This is mostly
  present for errors that are related to the request (e.g. insufficient funds) and not
  a specific parameter.
</ResponseField>

#### Examples

<CodeGroup>
  ```json HTTP 400 (with params) theme={"theme":"catppuccin-mocha"}
  {
      "code": "invalid_request",
      "detail": "The request is invalid.",
      "docs": "https://docs.engine.usesophic.com/api-reference/errors#invalid_request",
      "params": [
          {
              "path": "body.account_id",
              "detail": "Account not found",
              "code": "not_found"
          }
      ]
  }
  ```

  ```json HTTP 400 (with context) theme={"theme":"catppuccin-mocha"}
  {
      "code": "insufficient_funds",
      "detail": "The account has insufficient funds to cover the requested operation.",
      "docs": "https://docs.engine.usesophic.com/api-reference/errors#insufficient_funds",
      "context": {
          "available": "1000"
      }
  }
  ```

  ```json HTTP 401 theme={"theme":"catppuccin-mocha"}
  {
      "code": "invalid_token",
      "detail": "The access token is invalid or has expired.",
      "docs": "https://docs.engine.usesophic.com/api-reference/errors#invalid_token"
  }
  ```

  ```json HTTP 500 theme={"theme":"catppuccin-mocha"}
  {
      "code": "server_error",
      "detail": "The service encountered an unexpected error.",
      "docs": "https://docs.engine.usesophic.com/api-reference/errors#server_error"
  }
  ```
</CodeGroup>

<Panel>
  <Table title="Common HTTP status codes " columns={httpStatusTableColumns} data={httpStatuses} rowKey="status" />
</Panel>

## Debugging errors

In addition to error codes returned from API responses, you can inspect the response
headers for a unique request ID (`Request-Id`). This ID is assigned as soon as the
request is received and is used to identify the request in our logs.

We recommend logging request IDs in your production deployments for more efficient
troubleshooting with our [support team](hello@usesophic.com), should the need arise.

### Client request IDs

In addition to our request IDs, you can also supply your own request IDs via the
`Client-Request-Id` header. This header is not added automatically; you must explicitly
set it on the request.

The format is up to you; we recommend using a UUID or your internal trace ID up to a
maximum of 255 characters. We will reject any request with a `Client-Request-Id` header
that is longer than 255 characters.

If you supply a client request ID, we will log this value in our internal logs so make
sure it is not leaking any sensitive information. In cases of timeouts or network issues
when you can"t get the `Request-Id` response header, you can share the `Client-Request-Id`
value with our support team, and we can look up whether we received the request and when.