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

# Error handling

> This page lists the error codes and response structures returned by the Transaction and Activity Monitoring API, with example payloads for each scenario. 

## Error handling

The FrankieOne API uses a standardized error format to ensure that you can reliably handle issues that arise from bad requests, server problems, or invalid data. All non-2xx responses will return a consistent JSON error object.

For a full list of error types and their meanings, see the [API Error Codes](/docs/reference/error-codes) documentation. This document replaces any specific error handling guides for individual products unless explicitly stated otherwise.

### Scenarios

The error response format is the same across all Transaction and Activity Monitoring API endpoints, including [Evaluate an activity](/v2/docs/tm/implementation-evaluate-activity), [Resolve alerts](/v2/docs/tm/implementation-resolve-reevaluate), and [Classify activities](/v2/docs/tm/classifying-activities-and-alerts). The examples below use the evaluate endpoint, but the response structure applies to all.

### Generic Bad request

**HTTP Status Code : FrankieOne Error Code**

`400 : VAL-0400`

```json theme={null}
{
  "details": [
    {
      "issue": "request body has an error: doesn't match schema #/components/schemas/...",
      "issueLocation": "Request",
      "issueType": "Bad Request"
    }
  ],
  "errorCode": "400",
  "errorMsg": "Bad Request",
  "requestId": "01K8SQNX22ZC66XKHMQ1324RJC"
}
```

### Bad request - Validation issues (Any business or process validation)

**HTTP Status Code : FrankieOne Error Code**

`400 : VAL-0400`

```json theme={null}
{
    "errorCode": "VAL-0400",
    "errorMsg": "Validation failed",
    "details": [
        {
            "issue": "{message}",
            "issueLocation": "{location}"
        }
    ],
    "requestId": "01GVEDZ0C1Q9NWQ699DBBKPE4Y"
}
```

### Bad request - Schema issues

* Invalid limit or page parameter
* `beforeActivityAt` is earlier than `afterActivityAt`
* Invalid sortField other than `activityAt`
* `afterActivityAt` is in the future

**HTTP Status Code : FrankieOne Error Code**

`400 : VAL-0400`

```json theme={null}
{
  "details": [
    {
      "issue": "request body has an error: doesn't match schema #/components/schemas/Evaluate-Activity-Req: Error at \"/activity/detail\": ...",
      "issueLocation": "Request",
      "issueType": "Bad Request"
    }
  ],
  "errorCode": "400",
  "errorMsg": "Bad Request",
  "requestId": "01K8SQNX22ZC66XKHMQ1324RJC"
}
```

<Note>
  Schema validation errors include the full OpenAPI path in the `issue` field, which can be long. Parse `issueLocation` for the affected property.
</Note>

### Bad request - Entity not found

**HTTP Status Code : FrankieOne Error Code**

`400 : VAL-0404`

```json theme={null}
{
    "errorCode": "VAL-0404",
    "errorMsg": "Entity not found",
    "details": [
        {
            "issue": "The specified entity does not exist",
            "issueLocation": "body.party.entityId"
        }
    ],
    "requestId": "01GVEDZ0C1Q9NWQ699DBBKPE4Y"
}
```

### Duplicated transactions

**HTTP Status Code : FrankieOne Error Code**

`409 : VAL-0409`

```json theme={null}
{
  "errorCode": "VAL-0409",
  "errorMsg": "Validation failed",
  "details": [
    {
      "issue": "The transaction with the provided identifier already exists.",
      "issueLocation": "activity.detail.transaction.transactionIdentifier" 
    }
  ],
  "requestId": "01HN9XHZN6MGXM9JXG50K59Q88"
}
```

### System errors

**HTTP Status Code : FrankieOne Error Code**

`500 : SYS-0500`

```json theme={null}
{
    "errorCode": "SYS-0500",
    "errorMsg": "Provider service error",
    "details": [
        {
            "issue": "Failed to evaluate activity",
            "issueLocation": "connector"
        }
    ],
    "requestId": "01GVEDZ0C1Q9NWQ699DBBKPE4Y"
}
```

## More resources

* [Implementation Overview](/v2/docs/tm/implementation) — return to the full implementation map
* [Evaluate an activity](/v2/docs/tm/implementation-evaluate-activity) — check your request payload structure
* [Key terms and definitions](/v2/docs/tm/concepts-and-definitions) — reference for all TM terminology