GİB Error Responses and the SAP Correction Flow

Not every unsuccessful GİB e-Beyan response should trigger “send again.” An invalid token, missing authorization, invalid data, period rule, and temporary service failure require different owners and correction steps. A generic “transaction failed” message in SAP discards diagnostic information supplied by GİB.

GİB error classes

GİB’s KDV1 and Corporate Provisional Tax API documentation defines common classes:

HTTP status	Example class	First routing in SAP
`400`	JSON, data-format, or field-validation error	Data/mapping owner
`401`	Authentication failed	Integration and security owner
`403`	Not authorized for the resource or operation	Authorization and taxpayer owner
`404`	Resource or endpoint not found	Integration configuration
`422`	Valid data that violates a business rule	Tax process owner
`500`	Unexpected system error	Technical monitoring and GİB status check

The HTTP status is not sufficient on its own. GİB’s documentation says an error response can also contain a message description, a message identifier indicating the tab and row, and a system message code. Store these as separate fields in the SAP transaction record.

Information required in the SAP error record

Capture at least this context:

Company code, declaration type, and tax period
SAP transaction and source-document identifier
GİB declaration identifier when available
Environment, service, and operation
HTTP status, GİB message code, and description
Tab, row, or field identifier
First error time, latest attempt, and attempt count
Assigned owner, correction note, and revalidation result

Do not write API keys, personal data, or an unnecessary full request body to user-facing errors or general logs.

Correction workflow

1. Classify the response

Separate connectivity, authentication, authorization, data-format, business-rule, and GİB service errors. Do not automatically retry an unclassified error.

2. Link it to the source

When the response identifies a field or row, direct the user to the related SAP source record—not only to a message list. The process owner must decide whether the correction belongs in the source or an authorized declaration adjustment.

3. Record the correction

Keep the previous and new values, person, timestamp, and explanation. If the source document cannot be changed, do not override the target value without a documented exception and authorized approval.

4. Run local checks again

Recalculate dependent totals and reconciliations, not only the failed field. Use the role model to decide whether the correction invalidates the previous internal approval.

5. Query GİB status

A timeout or disconnected client does not prove that GİB created no transaction. Query the existing declaration or upload state before creating another submission. This reduces uncontrolled duplicate processing for the same period.

6. Reprocess under control

Do not automatically retry persistent 400, 403, or 422 data and authorization errors before correction. Even temporary failures need a delay, attempt limit, and final status query. Link every new attempt to the preceding error record.

File-upload errors

Some GİB API flows upload large files in chunks. The documentation describes states such as accepted for processing, processing, processed successfully, erroneous, and cancelled, with a separate error file for failed rows.

The SAP interface should not hide this asynchronous flow behind one indefinite spinner. Show the upload identifier, number of uploaded chunks, latest status, and error-file link in the transaction record.

Read the SAP E-Beyanname integration architecture for context and the implementation checklist for go-live tests. The interactive simulation of the Fenikstech SAP E-Beyanname solution shows how internal controls and GİB responses can be handled in the same workflow.

Official sources

This article was reviewed against the official sources on 23 July 2026.