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

# Errors

> Understanding and handling API errors

# Errors

Docyard uses standard HTTP status codes and returns structured error responses.

## Error Response Format

All errors follow this structure:

```json theme={null}
{
  "error": "error_code",
  "message": "Human-readable description",
  "details": { ... },
  "request_id": "req-abc123xyz"
}
```

| Field        | Description                          | Example                                |
| ------------ | ------------------------------------ | -------------------------------------- |
| `error`      | Machine-readable error code          | `validation_error`                     |
| `message`    | Human-readable description           | "The policy\_number field is required" |
| `details`    | Additional context (when applicable) | `{ "field": "policy_number" }`         |
| `request_id` | Unique request identifier            | `req-abc123xyz`                        |

## HTTP Status Codes

| Status Code | Meaning               |
| ----------- | --------------------- |
| `200`       | Success               |
| `201`       | Created               |
| `204`       | No Content            |
| `400`       | Bad Request           |
| `401`       | Unauthorized          |
| `403`       | Forbidden             |
| `404`       | Not Found             |
| `409`       | Conflict              |
| `422`       | Validation Error      |
| `429`       | Rate Limited          |
| `500`       | Internal Server Error |

## Authentication Errors

### `authentication_required`

**Status**: 401

```json theme={null}
{
  "error": "authentication_required",
  "message": "API key and secret are required",
  "request_id": "req-abc123xyz"
}
```

**Solution**: Include `X-API-Key` and `X-API-Secret` headers.

### `invalid_api_key`

**Status**: 401

```json theme={null}
{
  "error": "invalid_api_key",
  "message": "The provided API key is invalid",
  "request_id": "req-abc123xyz"
}
```

**Solution**: Check that you're using the correct API key.

### `invalid_api_secret`

**Status**: 401

```json theme={null}
{
  "error": "invalid_api_secret",
  "message": "The provided API secret is incorrect",
  "request_id": "req-abc123xyz"
}
```

**Solution**: Check that you're using the correct API secret.

### `api_key_expired`

**Status**: 401

```json theme={null}
{
  "error": "api_key_expired",
  "message": "The API key has expired. Please rotate your keys.",
  "request_id": "req-abc123xyz"
}
```

**Solution**: Rotate your API keys.

## Validation Errors

### `validation_error`

**Status**: 422

```json theme={null}
{
  "error": "validation_error",
  "message": "Request validation failed",
  "details": {
    "field": "locks.policy_number",
    "issue": "required"
  },
  "request_id": "req-abc123xyz"
}
```

**Solution**: Fix the validation issue and retry.

### `invalid_data_type`

**Status**: 422

```json theme={null}
{
  "error": "validation_error",
  "message": "Invalid data type for field",
  "details": {
    "field": "locks.effective_date",
    "expected": "date",
    "received": "string"
  },
  "request_id": "req-abc123xyz"
}
```

**Solution**: Ensure the field value matches the expected data type.

### `invalid_format`

**Status**: 422

```json theme={null}
{
  "error": "validation_error",
  "message": "Field does not match required format",
  "details": {
    "field": "locks.policy_number",
    "pattern": "^POL-[0-9]{8}$"
  },
  "request_id": "req-abc123xyz"
}
```

**Solution**: Ensure the value matches the validation pattern.

## Access Errors

### `access_denied`

**Status**: 403

```json theme={null}
{
  "error": "access_denied",
  "message": "You do not have permission to perform this action",
  "request_id": "req-abc123xyz"
}
```

**Solution**: Ensure you're using the correct credentials for your role.

### `insufficient_score`

**Status**: 403

```json theme={null}
{
  "error": "insufficient_score",
  "message": "Score (5) is below threshold (20)",
  "details": {
    "score": 5,
    "threshold": 20,
    "keys_provided": ["mortgagee_name"]
  },
  "request_id": "req-abc123xyz"
}
```

**Solution**: Provide additional keys to meet the threshold.

### `unauthorized_lock_type`

**Status**: 403

```json theme={null}
{
  "error": "unauthorized_lock_type",
  "message": "You are not authorized to use the 'tax_id' lock type",
  "request_id": "req-abc123xyz"
}
```

**Solution**: Request permission for this lock type from Docyard admin.

## Resource Errors

### `not_found`

**Status**: 404

```json theme={null}
{
  "error": "not_found",
  "message": "Artifact not found",
  "details": {
    "resource_type": "artifact",
    "resource_id": "art-nonexistent"
  },
  "request_id": "req-abc123xyz"
}
```

**Solution**: Verify the resource ID exists.

### `template_not_found`

**Status**: 404

```json theme={null}
{
  "error": "template_not_found",
  "message": "Template not found or not published",
  "details": {
    "template_id": "tmpl-nonexistent"
  },
  "request_id": "req-abc123xyz"
}
```

**Solution**: Use a published template ID.

### `artifact_revoked`

**Status**: 410

```json theme={null}
{
  "error": "artifact_revoked",
  "message": "This artifact has been revoked by the distributor",
  "request_id": "req-abc123xyz"
}
```

**Solution**: Contact the distributor for re-upload.

## Rate Limiting

### `rate_limit_exceeded`

**Status**: 429

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please retry after 60 seconds.",
  "details": {
    "retry_after": 60,
    "limit": 100,
    "window": "60 seconds"
  },
  "request_id": "req-abc123xyz"
}
```

**Solution**: Wait and retry after the specified time.

## Server Errors

### `internal_error`

**Status**: 500

```json theme={null}
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again.",
  "request_id": "req-abc123xyz"
}
```

**Solution**: Retry the request. If the issue persists, contact support with the `request_id`.

### `service_unavailable`

**Status**: 503

```json theme={null}
{
  "error": "service_unavailable",
  "message": "Service temporarily unavailable. Please try again later.",
  "request_id": "req-abc123xyz"
}
```

**Solution**: Retry after a few minutes.

## Error Handling Best Practices

### 1. Always Check Status Codes

```javascript theme={null}
const response = await client.upload endpoint.upload(data);

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

// Success
processResult(response.data);
```

### 2. Log Request IDs

Always include `request_id` when contacting support:

```javascript theme={null}
catch (error) {
  console.error('Docyard Error:', {
    error: error.error,
    message: error.message,
    requestId: error.request_id
  });
}
```

### 3. Implement Retry Logic

For transient errors:

```javascript theme={null}
async function uploadWithRetry(data, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await client.upload endpoint.upload(data);
    } catch (error) {
      if (error.status === 429 || error.status >= 500) {
        await sleep(1000 * (i + 1)); // Exponential backoff
        continue;
      }
      throw error;
    }
  }
}
```

### 4. Handle Validation Errors Gracefully

```javascript theme={null}
const response = await client.upload endpoint.upload(data);

if (response.status === 422) {
  const { details } = await response.json();
  
  if (details.field) {
    showFieldError(details.field, details.issue);
  }
}
```

## Contacting Support

When contacting support, always include:

1. **Request ID**: Found in every error response
2. **Endpoint**: The API endpoint you were calling
3. **Timestamp**: When the error occurred
4. **Request payload**: (Remove sensitive data)

Email: [support@docyard.io](mailto:support@docyard.io)

***

## Next Steps

* **[Authentication](/introduction/authentication)** - API authentication
* **[API Reference](/api-reference/overview)** - Full API documentation