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

# Errors

> Understanding API error responses

All error responses from the Smokeball API follow [Microsoft's ProblemDetails standard](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.mvc.problemdetails) (RFC 7807), with one extension described below.

## ProblemDetails

<ParamField path="type" type="string">
  A URI reference that identifies the problem type. When dereferenced, it provides human-readable documentation for the problem.

  Example: `https://tools.ietf.org/html/rfc7231#section-6.5.1`
</ParamField>

<ParamField path="title" type="string">
  A short, human-readable summary of the problem type. Does not change between occurrences of the same problem.

  Example: `"One or more validation errors occurred."`
</ParamField>

<ParamField path="status" type="integer">
  The HTTP status code for this occurrence.

  Example: `400`
</ParamField>

<ParamField path="detail" type="string">
  A human-readable explanation specific to this occurrence of the problem.

  Example: `"See the errors field for details."`
</ParamField>

<ParamField path="instance" type="string">
  A URI reference that identifies the specific occurrence.
</ParamField>

<ParamField path="errors" type="array">
  An array of error objects describing individual validation or field-level errors. See [the errors field](#the-errors-field) below.
</ParamField>

## Example Response

```json theme={"dark"}
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "detail": "See the errors field for details.",
  "instance": "/contacts",
  "errors": [
    { ... }
  ]
}
```

## Common Error Types

Here are some common HTTP error responses you may encounter when working with the Smokeball API:

### 400 Bad Request

This means there is something wrong with the request you sent.

Common examples:

* A required field is missing
* A field value is in the wrong format
* You sent a value the API does not accept

### 403 Forbidden

This means the request was valid, but you are not allowed to do it.

Common examples:

* Your API key, client ID, or client secret is wrong
* Your credentials have expired or were revoked
* Your app does not have the scope needed for this endpoint
* The signed-in user does not have access to that record or action

### 404 Not Found

This means the API could not find what you asked for.

Common examples:

* The URL or endpoint is wrong
* The record ID does not exist
* You are calling the right endpoint in the wrong environment

## Extensions

### errors

The `errors` field is a Smokeball extension to the ProblemDetails standard.

The ProblemDetails standard leaves the shape of `errors` loosely defined. Smokeball returns `errors` as an **array of objects** instead. There are two reasons for this:

1. **Multiple errors per field**: a dictionary approach typically collapses all messages for a field into a string array, losing any structured metadata (such as error codes) attached to each individual error.
2. **Preserved ordering**: an array guarantees that errors are returned in a stable, meaningful order (e.g. the order fields appear in the request body), whereas dictionary key ordering is not guaranteed across all languages and runtimes.