Understanding Job Statuses and Errors

When you upload a file – a batch of Mail, a Contacts update, or similar – Payreq Delivery checks it against the Payreq Interface Specification before processing it. If the file doesn't meet the spec, the Job shows an Error status instead of completing. This article covers what that means, common causes, and how to fix and resubmit the file. See What are Jobs? for what a Job is in general.

Before anything else: make sure the right person is actually notified when a Job fails. Job errors aren't shown anywhere unless someone checks the Jobs tab, so if nobody has A job has failed turned on in their notification settings, a failed file can sit unnoticed. See "Get notified when a Job fails" further down this article.

Job statuses

Payreq reports these four Job statuses:

What causes a Job to error

An Error status means the file failed validation before Payreq processed any of it, or stopped partway through. This is separate from Undeliverable, which is a per-document review flag that can appear after a successful load, when one delivery channel fails for an otherwise-processed document – see Handling Undeliverable Mail for that scenario. This article covers file-level Job errors specifically.

The general fix, in every case, is the same:

1. Read the error message shown in the Job's details.
2. Check the relevant section of the Payreq Interface Specification for the file type involved (Contacts, Bill, Payroll, or External).
3. Correct the file.
4. Give the corrected file a new, unique File ID – Payreq rejects a resubmission that reuses a previous File ID.
5. Resubmit.

See Payreq Interface Specification for the full spec.

If you're not sure how to correct a file yourself, your mailhouse or technical contact who generates the file is usually best placed to make the fix, since it typically means adjusting the file-generation process rather than the individual file.

First things to check

Before digging into a specific error message, these cover most causes:

• Column count. The most common fault. A Contacts row needs 19 columns, a Bill row needs 32 (older 4.x interface versions) or 50 (5.1.0), a line-item row needs 14, a Payroll row needs 11, and an External row needs 3. Optional fields can be blank, but the column (and its delimiting comma) still needs to be there.
• Trailer count. The trailer record's count must match the number of data rows in the file (excluding the header and trailer itself).
• File ID uniqueness. Every file you send needs a unique File ID. Reusing one from an earlier file – even a failed one – causes a rejection.
• Character set. Use plain ASCII characters only, including in filenames. Accented characters anywhere in the file can break processing.
• Interface version. The version number in the file header must match what's expected for that file type – Contacts files use 4.0.0, Bill files use 5.1.0 (or the legacy 4.5.0), External files use 4.0.0, and Payroll files use 4.2.0.

Common error examples

These are real examples from recent failed Jobs, showing the kind of error message you might see and how each was resolved:

A note on troubleshooting these. Payreq stops validating a file at the first row that fails, so the error message only tells you about one problem – there may be others further into the file. Check every row against the spec before resubmitting, not just the one named in the error.

If a Job seems stuck rather than errored

Occasionally a Job remains at pending-file rather than moving to in-progress. If the file was submitted via the API rather than uploaded through the console, this can mean the file wasn't found where expected when the Job ran. Double-check that the referenced filename matches exactly, and allow a few minutes before assuming something is wrong because file transfer can be queued rather than instant.

Get notified when a Job fails

A Job doesn't push an alert to anyone by default – an Error status just sits in the Jobs tab until someone looks. For anything time-sensitive (a bill run, a Contacts update ahead of a deadline), that's too slow to rely on.

Make sure at least one appropriate user – someone who can either fix the file themselves or knows who to forward it to (your mailhouse or technical contact) – has the A job has failed notification turned on, ideally set to Immediately. This is a per-user setting, not account-wide, so it's worth checking who actually has it enabled rather than assuming someone does.

See User Notifications for how to set this up, and Managing Users in Payreq Delivery for reaching a user's notification settings in the first place. If your organisation uses a mailhouse to generate files, it's worth confirming with them who on their side should also be notified, so a failure doesn't wait on someone at your end to notice it before it's even passed along.

When to contact Payreq Support

If you've checked the file against the spec and the fix still isn't clear, or the same file keeps failing after correction, contact Payreq Support rather than guessing further. Include:

• The full error message from the Job's details.
• The header row of the file.
• One example of a failing data row (with any personal information removed).

Submit a ticket with this information so Payreq Support can investigate without needing to ask for it separately.

Related articles

• What are Jobs?
• Payreq Interface Specification
• Uploading Mail
• Handling Undeliverable Mail
• User Notifications