# Errors

## Notes

* The errors returned by the middleware are technical- not meant to be used in a user-facing application.
* Please use these messages for internal logging and map them to user-friendly messages depending on your particular app architecture and use case.
* When reporting an error to Finqware, please include the provided `id`.

## Schema

API errors respect this common structure:

```javascript
{
  "id": String,
  "type": String,
  "http": Integer,
  "code": String,
  "message": String
}
```

Description of fields:

* id: an error id used for debugging
* type: a more generic class of errors
* http: a standard http code (200, 4xx, 5xx)
* code: a more specific error code
* message: developer friendly message and eventual hints

### Invalid requests

Errors generated due to incorrect input.

```javascript
{
  "id": "uuid",
  "type": "invalid_request",
  "http": 400 | 404,
  "code": "missing_fields" | 
          "unknown_fields" |
          "invalid_field" |
          "invalid_credentials_id" |
          "invalid_client_id" |
          "invalid_client_secret" |
          "invalid_access_token" |
          "invalid_input" |
          "invalid_body" |
          "invalid_headers" |
          "not_found" |
          "invalid_step" |
          "invalid_session_id" |
          "invalid_skill_name" |
          "invalid_pcd_data_retention" |
          "tpp_redirect_error" 
  "message": "Detailed error message"
}
```

### Unauthorized

Errors generated due to incorrect input, related to various security tokens.

```javascript
{
  "id": "uuid",
  "type": "unauthorized",
  "http": 401,
  "code": "invalid_api_keys" |
          "unauthorized_tenant" |
          "invalid_access_token" |
          "invalid_credentials_id" |
          "invalid_client_id" |
          "invalid_client_secret" |
          "invalid_client_app_key" |
          "inactive_credentials" |
          "expired_credentials" |
          "invalid_uuid" |
          "invalid_tenant_keys" |
          "invalid_api_keys" |
          "invalid_temp_token"
  "message": "Detailed error message"
}
```

### External API errors

Errors generated by external APIs. Sometimes these errors are returned even when correct input is provided.

```javascript
{
  "id": "uuid",
  "type": "external_api_error",
  "http": 400,
  "code": "external_api_connection_error" |
          "external_api_too_many_requests" |
          "external_api_unauthorized" |
          "external_api_forbidden" |
          "external_api_duplicated_consent" |
          "external_api_expired_consent" |
          "external_api_invalid_psu_id" |
          "external_api_server_error" |
  "message": "Detailed error message"
}
```

### Internal server errors

```javascript
{
  "type": "server_error",
  "http": 500,
  "code": "internal_server_error" |
          "planned_maintenance"
  "message": "Detailed error message"
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.finqware.com/api/errors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.