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

{
  "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. |

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).   |

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.