# Errors

All Platform API endpoints use a consistent error format. When a request fails, the response body contains an `error` object with a human-readable message and a machine-readable code.

## Error Format

```json
{
  "error": {
    "message": "No active outbound flow found for partner with id abc-123. Ensure the flow exists and is set to 'Active'.",
    "code": "not_found"
  }
}
```

- `message` -- a description of what went wrong, intended for developers. May include specific identifiers to help with debugging.
- `code` -- a short, stable string you can use in your code to handle specific error cases.

## HTTP Status Codes

```
| Status | Meaning                                                                 |
|--------|-------------------------------------------------------------------------|
| 200    | Success. The request was processed and the response contains the result. |
| 400    | Bad request. A required parameter is missing or a value is invalid.      |
| 401    | Unauthorized. The API key is missing or invalid.                         |
| 404    | Not found. The requested resource does not exist.                        |
| 422    | Unprocessable. The request is valid but cannot be completed due to a configuration issue. |
| 429    | Too many requests. You have exceeded the rate limit; retry after the delay in the Retry-After header. |
```

## Error Codes

```
| Code                | Status | Description                                                          |
|---------------------|--------|----------------------------------------------------------------------|
| unauthorized        | 401    | The API key is missing or does not match any key in the system.       |
| missing_parameter   | 400    | A required field (such as contents) was not provided.                 |
| invalid_filename    | 400    | The filename contains disallowed characters or exceeds 128 characters. |
| invalid_envelope    | 400    | The envelope configuration is incomplete or contains invalid values.   |
| not_found           | 404    | The partner, flow, transaction setting, result, or artifact was not found. |
| configuration_error | 422    | The flow configuration is ambiguous (e.g., multiple matching nodes).   |
| rate_limited        | 429    | Too many requests in the rate-limit window. Retry after the Retry-After interval. |
```

## Rate Limits

Platform API requests are rate-limited per API key:

- **Read endpoints** (fetching results, artifacts, and the feed): 240 requests per minute.
- **Write endpoints** (submitting EDI or JSON): 240 requests per minute.

When you exceed a limit, the API responds with `429` and a `Retry-After` header giving the number of seconds to wait:

```json
{
  "error": {
    "message": "Rate limit exceeded. Please try again later.",
    "code": "rate_limited"
  }
}
```

Wait for the `Retry-After` interval before retrying, and use exponential backoff if you keep hitting the limit.

If your integration needs higher limits, [contact us](https://tediware.com/contact) and we'll be happy to help.

## Handling Errors

A general approach to error handling:

- **401** -- check that your API key is correct and has not been revoked
- **400** -- review the request body for missing or malformed fields. The `message` will indicate which field is problematic.
- **404** -- verify that the partner key, transaction set code, or resource ID is correct. For flow-related errors, confirm that the partner has an active flow for the expected direction.
- **422** -- this typically indicates a problem with your flow configuration in the application. Check the flow builder for the affected partner.
- **429** -- you are exceeding the rate limit. Wait for the `Retry-After` interval and back off before retrying.