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

# Error Codes

> Understanding API error responses and status codes

<Warning>These API docs are under construction and prone to change.</Warning>

# Error Codes

The Fyndera API uses standard HTTP status codes and returns detailed error information in JSON format to help you understand and resolve issues.

## Error Response Format

All error responses follow this consistent format:

```json theme={null}
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": "Additional context or suggestions",
    "requestId": "unique-request-identifier",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
```

## HTTP Status Codes

### 2xx Success

* **200 OK** - Request successful
* **201 Created** - Resource created successfully
* **204 No Content** - Request successful, no content returned

### 4xx Client Errors

* **400 Bad Request** - Invalid request parameters or malformed request
* **401 Unauthorized** - Authentication required or invalid API key
* **403 Forbidden** - Valid authentication but insufficient permissions
* **404 Not Found** - Requested resource not found
* **422 Unprocessable Entity** - Valid request format but semantic errors
* **429 Too Many Requests** - Rate limit exceeded

### 5xx Server Errors

* **500 Internal Server Error** - Unexpected server error
* **502 Bad Gateway** - Server acting as gateway received invalid response
* **503 Service Unavailable** - Server temporarily unavailable
* **504 Gateway Timeout** - Server acting as gateway timed out

## Common Error Codes

### Authentication Errors

<ResponseField name="401" type="object">
  <Expandable title="Unauthorized">
    <ResponseField name="INVALID_API_KEY" type="string">
      The provided API key is invalid or malformed
    </ResponseField>

    <ResponseField name="MISSING_API_KEY" type="string">
      No API key provided in the request
    </ResponseField>

    <ResponseField name="EXPIRED_API_KEY" type="string">
      The API key has expired
    </ResponseField>
  </Expandable>
</ResponseField>

**Example Response:**

```json theme={null}
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid",
    "details": "Please check your API key and ensure it's correctly formatted",
    "requestId": "req_123456789",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
```

### Validation Errors

<ResponseField name="400" type="object">
  <Expandable title="Bad Request">
    <ResponseField name="INVALID_PARAMETER" type="string">
      One or more request parameters are invalid
    </ResponseField>

    <ResponseField name="MISSING_REQUIRED_PARAMETER" type="string">
      A required parameter is missing
    </ResponseField>

    <ResponseField name="INVALID_DATE_FORMAT" type="string">
      Date parameter is not in the correct format (YYYY-MM-DD)
    </ResponseField>

    <ResponseField name="INVALID_ENUM_VALUE" type="string">
      Parameter value is not one of the allowed enum values
    </ResponseField>
  </Expandable>
</ResponseField>

**Example Response:**

```json theme={null}
{
  "error": {
    "code": "INVALID_ENUM_VALUE",
    "message": "Invalid value for documentType parameter",
    "details": "documentType must be one of: law, regulation, directive, decree, circular, guideline",
    "requestId": "req_123456790",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
```

### Rate Limiting Errors

<ResponseField name="429" type="object">
  <Expandable title="Too Many Requests">
    <ResponseField name="RATE_LIMIT_EXCEEDED" type="string">
      API rate limit has been exceeded
    </ResponseField>
  </Expandable>
</ResponseField>

**Example Response:**

```json theme={null}
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": "You have exceeded the rate limit of 100 requests per hour. Please wait before making additional requests.",
    "requestId": "req_123456791",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
```

### Server Errors

<ResponseField name="500" type="object">
  <Expandable title="Internal Server Error">
    <ResponseField name="INTERNAL_ERROR" type="string">
      An unexpected error occurred on the server
    </ResponseField>

    <ResponseField name="DATABASE_ERROR" type="string">
      Database connection or query error
    </ResponseField>

    <ResponseField name="EXTERNAL_SERVICE_ERROR" type="string">
      Error communicating with external services
    </ResponseField>
  </Expandable>
</ResponseField>

**Example Response:**

```json theme={null}
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred",
    "details": "Please try again later. If the problem persists, contact support.",
    "requestId": "req_123456792",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
```

## Error Handling Best Practices

### 1. Always Check Status Codes

```javascript theme={null}
const response = await fetch("/api/legislation");
if (!response.ok) {
  const error = await response.json();
  console.error("API Error:", error.error.message);
}
```

### 2. Handle Rate Limiting

```javascript theme={null}
if (response.status === 429) {
  const retryAfter = response.headers.get("Retry-After");
  console.log(`Rate limited. Retry after ${retryAfter} seconds`);
}
```

### 3. Implement Retry Logic

```javascript theme={null}
async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      if (response.ok) return response;

      if (response.status >= 500 && i < maxRetries - 1) {
        await new Promise((resolve) =>
          setTimeout(resolve, 1000 * Math.pow(2, i))
        );
        continue;
      }

      throw new Error(`Request failed: ${response.status}`);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}
```

### 4. Log Request IDs

Always include the `requestId` from error responses when contacting support:

```javascript theme={null}
const error = await response.json();
console.log(`Request ID for support: ${error.error.requestId}`);
```

## Troubleshooting Common Issues

### Invalid API Key

* Verify the API key is correct and active
* Check that you're using the `Bearer` prefix
* Ensure there are no extra spaces or characters

### Invalid Parameters

* Check parameter names are spelled correctly
* Verify enum values match the allowed options
* Ensure date formats are `YYYY-MM-DD`

### Rate Limiting

* By default, we process a maximum of 1.000 requests per hour
* If you need different limits, contact <a href="mailto:api-support@fyndera.be">[api-support@fyndera.be](mailto:api-support@fyndera.be)</a>
* Implement exponential backoff for retries

### Network Issues

* Check your internet connection
* Verify the API endpoint URL is correct
* Try the request again after a short delay

## Getting Help

If you encounter errors not covered in this documentation:

1. **Contact support**: [api-support@fyndera.be](mailto:api-support@fyndera.be)
2. **Include request details**: Always provide the `requestId` from error responses