About Sovos application responses

Application responses communicate document processing status through multiple status codes that describe your document's journey through the Sovos platform and tax authority systems.

Application responses are formatted in UBL 2.1 and carry status updates and attachments, such as cleared invoices, generated PDFs, or tax authority messages.

Where application responses appear

The Indirect Tax API returns application responses as Base64-encoded strings in the content field of the response in the following cases:


Method	Endpoint	Description
POST	`/documents`	Document creation. Returns an application response only when you specify one business scope (for example, mapping) in the new document (synchronous).
GET	`/documents/{countryCode}/{documentId}/notifications`	Returns all notifications for a given document.
GET	`/notifications/{countryCode}`	Lists notifications pending acknowledgment for a given country.
GET	`/notifications/{countryCode}/{notificationId}`	Retrieves a specific notification.

Response codes and status reason codes

Each application response contains one Sovos response code and several status reason codes that provide document status and help determine when further action is required.

The following response code and status reason codes can appear in the application response:


Code	Code type	Display frequency	Description
`SCIResponseCode`	Response code	Always	Shows the overall compliance status of the document.
`SCICloudStatusCode`	Status reason code	At least once	Provides more specific information about the status of the document and helps you understand why the document received a particular SCIResponseCode.
`SCIGovtStatusCode`	Status reason code	In some cases	Comes from the tax authority of the relevant market.
`SCIStatusAction`	Status reason code	In some cases	Informs you when additional action is required.
`SCIInternalValidation`	Status reason code	In some cases	Informs you when Sovos detects validation errors for market-specific validation. Shows the fields in the document that need to be fixed.

Note:

The system performs schema validation sequentially, from top to bottom, according to the structure of the schema (XSD) for the applicable market. Validation stops and returns an error as soon as it finds a mandatory field, so no further validation is performed on the remaining fields.

SCIResponseCode (primary)

SCIResponseCode is a two-letter response code that is always included in the application response. It provides the overall compliance status of a document, the primary processing logic for implementers, and indicates whether a document has been processed successfully.

This is the most important status element within the application response. Base your primary decision logic on this code.

SCICloudStatusCode (detailed)

SCICloudStatusCode is a unique three-digit status code that provides additional status information for the SCIResponseCode. This code appears one or more times in the application response.

SCICloudStatusCode provides specific information about which processing stage completed or failed, giving you context for the SCIResponseCode.

Elements:

StatusReason — Explains what the status code means.
Text — May be included to offer more in-depth details.

SCIGovtStatusCode (tax authority)

SCIGovtStatusCode comes directly from the tax authority of certain countries. Sovos collects the tax authority response and passes along the raw error message to the calling application or customer.

This code offers similar information to the Sovos-generated SCIResponseCode and SCICloudStatusCode. However, it is usually accompanied by a local language rationale for the error, such as:

Address field format is invalid
Tax ID length is incorrect
Duplicate invoice number
Invalid tax calculation

Elements:

StatusReason - Explains what the status code means (often in local language).
SequenceID - May be included to represent the legal tracking ID provided by the tax authority.

Tip:

For a comprehensive list of government status codes, go to the corresponding tax authority's website. Your country-specific implementation guide covers links to official tax authority error code documentation.

SCIStatusAction (action required)

SCIStatusAction is a three-letter status code based on SCIResponseCode. It identifies any additional required action and is included at least once in every application response.

SCIInternalValidation (validation errors)

SCIInternalValidation is a code that identifies country-specific schema validation errors. This code highlights the specific field or node that is causing validation errors so you can review and correct them.

When the Sovos validation service detects market-specific validation errors in the document, SCIInternalValidation appears in the application response showing exactly which fields need to be fixed.

Sample application response

A sample application response shows how status codes appear together in a single XML response.

<ApplicationResponse>
  <cac:DocumentResponse>
    <cac:Response>
      <!-- PRIMARY: Overall status -->
      <cbc:ResponseCode listID="SCIResponseCode">AP</cbc:ResponseCode>
      
      <!-- DETAILED: Sovos processing status -->
      <cac:Status>
        <cbc:StatusReasonCode listID="SCICloudStatusCode">200</cbc:StatusReasonCode>
        <cbc:StatusReason>Authorized by the tax authority</cbc:StatusReason>
      </cac:Status>
      
      <!-- TAX AUTHORITY: Government response -->
      <cac:Status>
        <cbc:StatusReasonCode listID="SCIGovtStatusCode">S100</cbc:StatusReasonCode>
        <cbc:StatusReason>Invoice authorized. Number: 278754</cbc:StatusReason>
        <cbc:SequenceID>278754</cbc:SequenceID>
      </cac:Status>
      
      <!-- ACTION: What to do -->
      <cac:Status>
        <cbc:StatusReasonCode listID="SCIStatusAction">NOA</cbc:StatusReasonCode>
        <cbc:StatusReason>No action required</cbc:StatusReason>
      </cac:Status>
    </cac:Response>
  </cac:DocumentResponse>
</ApplicationResponse>

You receive all of these status codes in a single response. Check them in order to understand the complete status.

How status codes work together

Status codes work together to tell the complete story of your document's processing status.

Reading the complete story

Step 1: Check SCIResponseCode first

This tells you the overall outcome:


Code	Name	Meaning	Next action
AP	Accepted	Document approved	Check SCICloudStatusCode for details, proceed with delivery.
RE	Rejected	Document rejected or error	Check SCICloudStatusCode and SCIGovtStatusCode for reason, fix, and resubmit.
IP	In Process	Still processing	Continue polling.
CA	Conditionally Accepted	Accepted with conditions	Check SCIGovtStatusCode for conditions.
AB	Acknowledgement	Receipt acknowledged	Continue polling.

Step 2: Check SCICloudStatusCode for specifics

This tells you which processing stage completed and provides the detailed explanation:

Important:

209 means "Workflow complete," not "Success." Check SCICloudStatusCode, StatusReason or SCIStatusAction for more information.

Step 3: Check SCIStatusAction

This tells you what action to take:

Tip:

The tax authority's raw response code and message, often in local language, are available in SCIGovtStatusCode . Use SCICloudStatusCode and StatusReason to drive your primary decision logic. Sovos has already interpreted the tax authority response so you get clear, actionable status information.

Interpreting combined status codes

Scenario 1: Document successfully authorized

SCIResponseCode: AP
SCICloudStatusCode: 200
StatusReason: "Invoice authorized by tax authority"
SCIStatusAction: NOA

Document authorized by tax authority. No further action needed.

Scenario 2: Document rejected

SCIResponseCode: RE
SCICloudStatusCode: 400
StatusReason: "Tax authority rejected: Invalid tax ID format"
SCIStatusAction: NIN

Tax authority rejected the document due to invalid tax ID. Fix the tax ID and submit a new invoice. Sovos has translated the tax authority's rejection reason into clear English.

Scenario 3: Still processing

SCIResponseCode: IP
SCICloudStatusCode: 105
StatusReason: "Tax authority is processing the document"
SCIStatusAction: NOA

Document transmitted, tax authority is processing. Continue polling for final status.

About document attachments

Application responses for authorized and completed documents typically include attachments such as cleared invoices and PDF renderings.

Application responses for status 200 (document.authorized) and 209 (workflow complete) typically include the following document attachments:

LegalCleared - Country-specific format with tax authority clearance metadata.
PDF - PDF rendering (if configured).

These attachments provide the cleared invoice and proof of authorization.

Processing multiple notifications

You may receive multiple notifications for a single document as it progresses through processing stages. Each notification represents an event or milestone.

Use documentId to correlate notifications.

Processing order

Use timestamps to process in chronological order. Notifications may arrive out of sequence. Use the createdAt timestamp to order notifications chronologically and track progression.

Track progression using SCICloudStatusCode:

100 > 101 > 104 > 105 > 200 (successful authorization)
100 > 101 > 400 (rejected)

Implement idempotent processing. Each notification has a unique notificationId. Track which notifications you have processed to avoid duplicate handling.

Determining final document status

The most important status element is the SCIResponseCode. A document is complete when you receive one of the final SCI response codes (AP, RE, or CA).

When you have multiple notifications, apply the following status code priority for final determination:

Highest priority: document.cancelled (201) — If a document was authorized then cancelled, the cancellation takes precedence.
Next: document.authorized (200) — Authorization status indicates tax authority approval.
Then: Rejection codes (400-404) — If no authorization or cancellation, check for rejection status.
Finally: In Process (IP) — If none of the previous conditions apply, the document is still processing.

Valid status code combinations

Not all status code combinations are valid. Understanding which combinations can occur helps you implement correct response handling logic.

Valid combinations


SCICloudStatusCode	SCIResponseCode	Scenario
100-105	IP	Processing stages
200	AP or CA	Authorization (standard or conditional)
201	AP	Cancellation successful
202	RE	Use denied
207	AP	PDF created
208	AB	Archived
209	AP	Workflow completed (check other status codes for outcome)
400	RE	Rejected
401	RE	Processing error
500-504	RE	System or network errors

Invalid combinations

If you observe any of the following combinations, it indicates a problem that you should report to Sovos:


SCICloudStatusCode	SCIResponseCode	Why invalid
200	RE	Authorization cannot be rejected.
400	AP	Rejection cannot be accepted.
201	RE	Cancellation cannot be rejected.

If you see invalid combinations in your application responses, flag them as problems. This helps Sovos identify and fix system problems.

Reference: SCIResponseCode values

SCIResponseCode is a two-letter response code that provides the overall compliance status of a document.


Code	Name	Description	Terminal?
AP	Accepted	Document accepted or workflow successful	Yes
RE	Rejected	Document rejected or processing failed	Yes
CA	Conditionally Accepted	Accepted with conditions	Yes
IP	In Process	Processing ongoing	No
AB	Message Acknowledgement	Receipt acknowledged	No
UQ	Under Query	Processing halted pending response	No
PD	Paid	Payment completed	Yes

Terminal codes (AP, RE, CA) indicate final status. Non-terminal codes (IP, AB, UQ) mean continue polling.

Reference: SCICloudStatusCode values

SCICloudStatusCode is a three-digit status code that provides detailed information about each processing stage.

The following table provides the complete reference for all status codes across all markets. Only a subset of these status codes are used in each country or region. Your country-specific implementation guide covers which status codes apply to your market.


Code	Event	SCIResponseCode	Description
100 series — Processing stages
100	`document.received`	IP	Document received by Sovos
101	`document.mapped`	IP	Transformed to canonical format
102	`document.validated`	IP	Schema validation passed
103	`document.signed`	IP	Digital signature applied
104	`document.transmitted`	IP	Sent to tax authority
105	`document.processing`	IP	Tax authority processing (may repeat)
106	`document.processingInternally`	IP	Sovos internal processing
107	`action.received`	AB	Action request received
108	`document.processingByRecipient`	IP	Buyer processing document
200 series — Success or completion
200	`document.authorized`	AP or CA	Tax authority authorized document
201	`document.cancelled`	AP	Document cancelled successfully
202	`document.denied`	RE	Use denied by tax authority
203	`document.acceptedByCounterparty`	AP	Buyer accepted document
204	`document.distributed`	AB	Delivered to recipient
205	`document.printed`	AB	Document printed
206	`document.finalized`	AP	Document finalized
207	`document.pdf.created`	AP	PDF generated
208	`document.archived`	AB	Stored for compliance
209	`document.completed`	AP	Workflow finished — check other status codes for outcome
210	`document.approved`	AP	Approved by counterparty
212	`document.commerciallyRejected`	AP	Rejection acknowledged
216	`document.acknowledgedByRecipient`	AP	Buyer acknowledged receipt
220	`document.paymentReceived`	220	Payment received
226	`document.query`	AP	Query response received
400 series — Document errors
400	`document.rejected`	RE	Tax authority rejected document
401	`document.error`	RE	Error processing document
402	`document.notFound`	RE	Document not found
403	`document.cancellationRejected`	RE	Cancellation request denied
404	`document.processedPreviously`	RE	Document already processed
405	`document.rejectedByCounterparty`	RE	Buyer rejected document
406	`document.alreadyInProgress`	RE	Duplicate submission detected
407	`document.signingFailed`	RE	Digital signature failed
500 series — System errors
500	`system.error`	RE	Internal system error
501	`taxAuthority.unavailable`	RE	Tax authority service down
502	`request.invalidParameters`	RE	Invalid input parameters
503	`request.invalidCredentials`	RE	Authentication failed
504	`process.Timeout`	RE	Processing timeout