Audience: Integrators, API developers, B2B integration teams

When you post an any file transaction to Orderful via the API, the request may fail and no transaction is created. This article covers the most common errors, how to fix them, and what to send support if you are still stuck. For the full API configuration reference, see Outbound MFT — Create and Send Any file.

How this works — expected behavior

You post the file to Orderful's POST /v3/transactions/raw endpoint with the required routing headers and your Orderful API key. Orderful uses those headers to identify the correct relationship, creates the transaction, stores the file, and delivers it to your partner via their configured inbound communication channel — exactly as you sent it. If successful, Orderful returns a 201 response code with the ID of the transaction created.

Required headers:

Content-Type — MIME type of the file (e.g. application/xml, text/csv, application/pdf)
orderful-sender-id — sender ISA ID or MFT identifier
orderful-receiver-id — receiver ISA ID or MFT identifier
orderful-transaction-type — Orderful Any file transaction type (e.g. ORDER, INVOICE)
orderful-stream — test or live
orderful-business-number — a human-readable reference for the file (e.g. PO number, shipment ID)
Authorization — your Orderful API key

What's the error?

The request will fail with a 422 or 400 response code. Common causes are invalid or missing headers, malformed file content, or routing metadata that does not map to an active relationship.

Fix 1 — unsupported Content-Type

What's happening: The Content-Type header value is not supported by Orderful for any file over MFT.

{
    "type": "argumentError",
    "ref": "Content-Type",
    "message": "Unsupported Content-Type: text/cvs. Supported types: application/json, application/xml, text/csv, application/pdf, image/jpeg"
}

How to fix it: Set Content-Type to one of the supported MIME types: application/json, application/xml, text/csv, application/pdf, or image/jpeg. Once corrected, resend the request.

Fix 2 — missing or incorrectly spelled routing header

What's happening: One or more of the required routing headers are absent or misspelled in the request.

{
    "type": "argumentError",
    "ref": "orderful-sender-id",
    "message": "orderful-sender-id header is required"
}

How to fix it: Confirm all required headers are present with the exact names:

orderful-sender-id
orderful-receiver-id
orderful-transaction-type
orderful-stream
orderful-business-number

Once corrected, resend the request.

Fix 3 — invalid stream value

What's happening: The orderful-stream header is present but its value is not valid. Stream must be test or live (lowercase).

{
    "type": "argumentError",
    "ref": "orderful-stream",
    "message": "Invalid orderful-stream value: testing. Must be one of: test, live"
}

How to fix it: Set orderful-stream to either test or live. Once corrected, resend the request.

Fix 4 — unsupported transaction type

What's happening: The orderful-transaction-type header value is not in the list of supported Any file transaction types.

{
    "statusCode": 400,
    "error": "HttpBadRequestError",
    "message": "Transaction type 'PURCHASE' not found"
}

How to fix it: Check the available transaction types and confirm the value matches exactly. Once corrected, resend the request.

Fix 5 — malformed file content

What's happening: The file content itself is not valid for the declared Content-Type.

{
    "statusCode": 400,
    "error": "HttpBadRequestError",
    "message": "Invalid PDF"
}

{
    "statusCode": 400,
    "error": "HttpBadRequestError",
    "message": "Invalid XML: Invalid space after '<'. (line 1)"
}

{
    "statusCode": 400,
    "error": "HttpBadRequestError",
    "message": "Invalid JSON"
}

How to fix it: Verify that the file you are sending is a valid, well-formed file for its declared type. Open the file locally to confirm it is not corrupted. Once corrected, resend the request.

Fix 6 — sender or receiver ID not found

What's happening: The sender or receiver ID in your routing headers does not match any EDI account in Orderful.

{
    "type": "unprocessableEntity",
    "ref": "senderIdentity",
    "message": "Cannot post transaction because the sender ISA ID MFTRADINGPDF doesn't exist."
}

{
    "type": "unprocessableEntity",
    "ref": "receiverIdentity",
    "message": "Cannot post transaction because the receiver ISA ID OBDCPP doesn't exist."
}

How to fix it: Go to Partnerships in Orderful and verify that the sender and receiver IDs in your headers match exactly what is configured on the partnership EDI accounts — including casing and spacing. Once corrected, resend the request.

Fix 7 — partnership not found

What's happening: Both the sender and receiver IDs exist in Orderful, but no partnership exists between them.

{
    "type": "unprocessableEntity",
    "ref": "partnership",
    "message": "Cannot post transaction because the partnership between the sender ISA ID OBDCA1 and receiver ISA ID MFTRADINGPDF doesn't exist."
}

How to fix it: Create a new trade request to trade Any file: Set up a Trading Partnership to trade Any file over MFT. Once the partnership and relationship are in place, resend the request.

Fix 8 — relationship not found

What's happening: A partnership exists between the sender and receiver, but no relationship exists for the transaction type you are sending.

{
    "type": "unprocessableEntity",
    "ref": "relationship",
    "message": "Cannot post transaction because the PURCHASE_ORDER relationship between the sender ISA ID MFTRADINGPDF and the receiver ISA ID OBDCA doesn't exist."
}

How to fix it: Go to Relationships within the partnership and confirm a relationship exists for the transaction type you are sending. Verify the transaction type in your header matches exactly what is configured — for example ORDER, not Order or PURCHASE_ORDER. If the relationship does not exist, create a change request from Scenario Checklists. Once in place, resend the request.

Fix 9 — data type mismatch

What's happening: A relationship exists, but the Content-Type of the file you are sending does not match the data format configured on the relationship.

{
    "type": "unprocessableEntity",
    "ref": "dataTypeMismatch",
    "message": "Data type mismatch(es) detected: incoming transaction data format CSV does not match the sender relationship data format PDF, incoming transaction data format CSV does not match the receiver relationship data format PDF"
}

How to fix it: Check the data format configured on the relationship in Orderful and confirm it matches the Content-Type of the file you are sending. Either update the Content-Type header to match the relationship, or update the relationship data format. Once corrected, resend the request.

Fix 10 — stream incompatible with relationship status

What's happening: A relationship exists, but the stream you are posting is not compatible with the relationship's current status.

{
    "type": "unprocessableEntity",
    "ref": "relationships",
    "message": "Cannot post transaction because the PURCHASE_ORDER relationship between the sender ISA ID OBDCA and the receiver ISA ID MFTRADINGPDF is in setup."
}

{
    "type": "unprocessableEntity",
    "ref": "relationships",
    "message": "Cannot post a LIVE transaction because the MFT_PURCHASE_ORDER relationship between the sender ISA ID MFTRADINGCSV and the receiver ISA ID OBDCA1 is in testing."
}

Relationship status	`test` transactions	`live` transactions
Setup	❌	❌
Test	✅	❌
Live	✅	✅

How to fix it:

Check the relationship status in Orderful and confirm it matches the stream you are posting.
- If you are testing and the relationship is in Setup, you and/or your partner must configure your relationship first. Once the relationship status is updated to Test, resend the request.
- If you need to send live transactions, make sure testing is completed or skipped from Scenario Checklists. Once the relationship has been moved to Go Live Ready or Live status, resend the request.

What to Send Orderful Support

If you cannot resolve the error, contact [email protected] with:

The full request headers you are sending (redact your API key)
The error response body
Your sender and receiver EDI account IDs and the transaction type used — or the relationship ID in Orderful

Frequently Asked Questions

What file formats can I send?

Orderful supports application/json, application/xml, text/csv, application/pdf, and image/jpeg. Set Content-Type to match your file format and send the raw bytes as the request body.

What transaction types can I use?

The orderful-transaction-type header must use one of Orderful's approved Any file transaction type names. See the available transaction types. Contact Orderful support if the type you need is not listed.

Can I send the same file to multiple partners in one request?

No. Each API request creates one transaction for one relationship. Submit a separate request for each partner.

I fail to create a transaction when sending any file over API — what's wrong?