Error handling

HTTP error codes

The following table lists the HTTP codes you may get from the Sovos Compliance Network, what each one means, and the action to take:

HTTP code	Meaning	Action
400	Malformed request or invalid Standard Business Document structure	Fix the request. Don't retry without changes.
401	Invalid or expired bearer token	Re-authenticate and retry.
403	Account not authorized for this product	Contact Sovos support.
409	Duplicate SenderDocumentId	Each invoice needs a unique ID. Poll first to check whether the original submission succeeded before resubmitting with a new ID.
422	PINT-AE validation failure	Read the error detail in the response. Fix the field errors and resubmit with a new SenderDocumentId.
429	Rate limit exceeded	Wait and retry with exponential backoff.
500	Transient platform error	Retry with backoff. Contact Sovos support if it persists.
503	Platform maintenance	Retry after the Retry-After period.

Common validation failures

The following table covers the most frequent validation errors, their causes, and how to fix them:

Error	Cause	Fix
Missing CustomizationID	PINT-AE specification identifier absent	Set to the full PINT-AE URN.
Invalid Tax Identification Number (TIN)	TIN is not exactly 10 digits	Verify from Federal Tax Authority (FTA) registration.
Invalid Tax Registration Number (TRN)	TRN is not a valid 15-digit alphanumeric	Verify from EmaraTax.
Missing buyer endpoint	AccountingCustomerParty.EndpointID absent	Supply the PEPPOL ID of the buyer before submitting.
AED tax amount missing	TaxTotal in AED not present	All invoices must include AED-equivalent tax totals.
INVALID_RECEIVER from ASP	Buyer TIN not found in PEPPOL network	Verify buyer has onboarded with an ASP.

Retry logic

The following example shows how to implement retry logic when submitting an invoice:

function submitWithRetry(invoicePayload, maxAttempts):
    attempt = 1
    delay = 5 seconds

    while attempt <= maxAttempts:
        response = submitInvoice(invoicePayload)

        if response.httpStatus == 200:
            return response.transactionId        // success — begin polling

        if response.httpStatus in [400, 422]:
            logError(response.errorDetail)
            return SUBMISSION_ERROR              // fix payload; do not retry

        if response.httpStatus == 409:
            pollForExistingStatus(invoicePayload.senderDocumentId)
            return DUPLICATE_CHECK_REQUIRED      // do not resubmit with same ID

        if response.httpStatus == 401:
            refreshToken()
            // retry immediately without incrementing delay

        if response.httpStatus in [429, 500, 503]:
            wait(delay)
            delay = delay * 2                    // exponential backoff
            attempt = attempt + 1

    return MAX_RETRIES_EXCEEDED

Retry rules

Retry on: 401, 429, 500, and 503.

Don't retry on: 400, 409, or 422. Fix the payload first, then resubmit.