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

# API Error Handling and Error Codes Reference

> IteraPay errors follow RFC 7807. Learn the error response shape, all status codes, and how to handle errors reliably in your integration.

When a request cannot be completed, IteraPay returns an error response with an appropriate HTTP status code. All error responses use the `application/problem+json` content type and follow the [RFC 7807 Problem Details](https://datatracker.ietf.org/doc/html/rfc7807) format.

## Error response shape

Every error response includes the following fields:

<ResponseField name="type" type="string">
  A URI that identifies the problem type. You can use this to classify errors programmatically.
</ResponseField>

<ResponseField name="title" type="string">
  A short, human-readable summary of the problem type. This does not change between occurrences of the same error type.
</ResponseField>

<ResponseField name="status" type="integer">
  The HTTP status code for this occurrence of the problem.
</ResponseField>

<ResponseField name="detail" type="string">
  A human-readable explanation specific to this occurrence. Use this field when surfacing errors to developers or in logs.
</ResponseField>

<ResponseField name="instance" type="string">
  A URI reference that identifies the specific occurrence. Typically the request path.
</ResponseField>

### Example error response

```json theme={null}
{
  "type": "https://example.com/probs/invalid-request",
  "title": "Invalid Request",
  "status": 400,
  "detail": "The 'amount' field must be a positive number",
  "instance": "/merchants/b0fcc813-a7ce-4bbc-932f-dbef6f59ca7f/invoices"
}
```

## Status codes

### 400 Bad Request

The request body or parameters are invalid. The `detail` field describes the specific validation failure.

```json theme={null}
{
  "type": "https://example.com/probs/invalid-request",
  "title": "Invalid Request",
  "status": 400,
  "detail": "The 'name' field is required",
  "instance": "/merchants"
}
```

### 401 Unauthorized

The request is missing credentials, or the provided credentials are invalid. Verify your `Authorization` header or `X-Api-Key` header is set correctly.

```json theme={null}
{
  "type": "https://example.com/probs/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Bearer token is missing or has expired",
  "instance": "/merchants"
}
```

### 403 Forbidden

The credentials are valid but the authenticated identity does not have permission to perform this action. This can happen when an API key is used on a merchant it was not issued for, or when your role lacks the required permission.

```json theme={null}
{
  "type": "https://example.com/probs/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Your API key does not have access to this merchant",
  "instance": "/merchants/b0fcc813-a7ce-4bbc-932f-dbef6f59ca7f"
}
```

### 404 Not Found

The requested resource does not exist. Check that the ID or path is correct.

```json theme={null}
{
  "type": "https://example.com/probs/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Merchant 'b0fcc813-a7ce-4bbc-932f-dbef6f59ca7f' not found",
  "instance": "/merchants/b0fcc813-a7ce-4bbc-932f-dbef6f59ca7f"
}
```

### Other status codes

All other errors use standard HTTP status codes. The `type`, `title`, and `detail` fields in the response body provide additional context.

## Handling errors in your code

Check the HTTP status code first, then inspect `type` for programmatic classification and `detail` for a human-readable description.

```javascript theme={null}
const response = await fetch('https://api.iterapay.com/merchants', {
  headers: { 'Authorization': `Bearer ${token}` },
});

if (!response.ok) {
  const error = await response.json();

  switch (response.status) {
    case 400:
      console.error('Invalid request:', error.detail);
      break;
    case 401:
      console.error('Authentication failed. Check your credentials.');
      break;
    case 403:
      console.error('Permission denied:', error.detail);
      break;
    case 404:
      console.error('Resource not found:', error.instance);
      break;
    default:
      console.error(`Unexpected error ${error.status}:`, error.detail);
  }
}
```

<Tip>
  Log the `instance` field alongside errors in your system. It identifies the exact request path where the problem occurred and makes debugging faster.
</Tip>