Skip to content

Commit

Permalink
[Self-service error codes] Fix section numbering in pdf for error cod…
Browse files Browse the repository at this point in the history 
…es section by moving it a level higher. (#11867)

Also make section header markers consistent docs' reamde.

CHANGELOG_BEGIN
CHANGELOG_END
  • Loading branch information
@pbatko-da
pbatko-da authored Nov 25, 2021
1 parent cf3ac01 commit 5f3a4d2
Show file tree
Hide file tree
Showing 6 changed files with 46 additions and 51 deletions.
44 changes: 22 additions & 22 deletions docs/source/app-dev/grpc/error-codes.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,15 +34,15 @@ The goal is to enable users, developers and operators to act on the encountered
errors in a self-service manner, either in an automated-way or manually.

Configuration
-------------
======================================

The new error code formats and adapted gRPC response statuses are returned by default starting with the Daml 1.18 SDK release.
Clients can still migrate to Daml SDK 1.18 and use the pre-1.18 gRPC status code response behavior by using ``--use-pre-1.18-error-codes``
as a command line option. However, this option is deprecated and will be removed in a future release.


Glossary
---------------------------
======================================

Error
Represents an occurrence of a failure.
Expand Down Expand Up @@ -82,14 +82,14 @@ Correlation id


Error Categories
---------------------------
======================================

The error categories allow to group errors such that application logic can be built
in a sensible way to automatically deal with errors and decide whether to retry
a request or escalate to the operator.

TransientServerFailure
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------
**Category id**: 1

**gRPC status code**: UNAVAILABLE
Expand All @@ -104,7 +104,7 @@ TransientServerFailure


ContentionOnSharedResources
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------
**Category id**: 2

**gRPC status code**: ABORTED
Expand All @@ -119,7 +119,7 @@ ContentionOnSharedResources


DeadlineExceededRequestStateUnknown
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------
**Category id**: 3

**gRPC status code**: DEADLINE_EXCEEDED
Expand All @@ -134,7 +134,7 @@ DeadlineExceededRequestStateUnknown


SystemInternalAssumptionViolated
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------
**Category id**: 4

**gRPC status code**: INTERNAL
Expand All @@ -149,7 +149,7 @@ SystemInternalAssumptionViolated


MaliciousOrFaultyBehaviour
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------
**Category id**: 5

**gRPC status code**: UNKNOWN
Expand All @@ -164,7 +164,7 @@ MaliciousOrFaultyBehaviour


AuthInterceptorInvalidAuthenticationCredentials
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------
**Category id**: 6

**gRPC status code**: UNAUTHENTICATED
Expand All @@ -179,7 +179,7 @@ AuthInterceptorInvalidAuthenticationCredentials


InsufficientPermission
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------
**Category id**: 7

**gRPC status code**: PERMISSION_DENIED
Expand All @@ -194,7 +194,7 @@ InsufficientPermission


InvalidIndependentOfSystemState
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------
**Category id**: 8

**gRPC status code**: INVALID_ARGUMENT
Expand All @@ -209,7 +209,7 @@ InvalidIndependentOfSystemState


InvalidGivenCurrentSystemStateOther
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------
**Category id**: 9

**gRPC status code**: FAILED_PRECONDITION
Expand All @@ -224,7 +224,7 @@ InvalidGivenCurrentSystemStateOther


InvalidGivenCurrentSystemStateResourceExists
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------
**Category id**: 10

**gRPC status code**: ALREADY_EXISTS
Expand All @@ -239,7 +239,7 @@ InvalidGivenCurrentSystemStateResourceExists


InvalidGivenCurrentSystemStateResourceMissing
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------
**Category id**: 11

**gRPC status code**: NOT_FOUND
Expand All @@ -254,7 +254,7 @@ InvalidGivenCurrentSystemStateResourceMissing


InvalidGivenCurrentSystemStateSeekAfterEnd
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------
**Category id**: 12

**gRPC status code**: OUT_OF_RANGE
Expand All @@ -269,7 +269,7 @@ InvalidGivenCurrentSystemStateSeekAfterEnd


BackgroundProcessDegradationWarning
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------
**Category id**: 13

**gRPC status code**: N/A
Expand All @@ -286,15 +286,15 @@ BackgroundProcessDegradationWarning


Anatomy of an Error
---------------------------
======================================


Errors returned to users contain a `gRPC status code`_, a description and additional machine readable information
represented in the `rich gRPC error model`_.


Error Description
^^^^^^^^^^^^^^^^^^^
--------------------------------------

We use the `standard gRPC description`_ that additionally adheres to our custom message format:

Expand Down Expand Up @@ -330,7 +330,7 @@ In a concrete example an error description might look like this:
Additional Machine Readable Information
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
----------------------------------------------------------------------------

We use following error details:

Expand Down Expand Up @@ -369,7 +369,7 @@ The table below outlines all the cases and error conditions when a Ledger API se
gRPC status code in comparison to the pre-1.18 releases.

Common Ledger API changes
---------------------------
======================================

The table below outlines generic gRPC status code changes pertaining to the Ledger API
and apply to all ledger backends. For changes specific to a ledger backend, check the next subsections.
Expand All @@ -379,7 +379,7 @@ and apply to all ledger backends. For changes specific to a ledger backend, chec
.. include:: status-codes-migration-table-ledger-api.rst

Sandbox (classic)
---------------------------
======================================

The following gRPC status codes have changed for submission rejections in Sandbox classic.

Expand All @@ -405,7 +405,7 @@ The following gRPC status codes have changed for submission rejections in Sandbo


Daml Sandbox and VMBC
---------------------------
======================================

The following gRPC status codes have changed for submission rejections in the Ledger API backed by KV-based ledgers (Daml Sandbox and VMBC).

Expand Down
6 changes: 0 additions & 6 deletions docs/source/app-dev/grpc/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -95,9 +95,3 @@ INTERNAL, UNKNOWN (when returned by the Command Service)
Aside from the standard gRPC status codes, the failures returned by the Ledger API are enriched with details meant to help the application
or the application developer to handle the error autonomously (e.g. by retrying on a retryable error).
For more details on the rich error details see the :doc:`error-codes`


.. toctree::
:hidden:

error-codes
36 changes: 18 additions & 18 deletions docs/source/app-dev/grpc/status-codes-migration-table-ledger-api.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
.. SPDX-License-Identifier: Apache-2.0
ActiveContractsService.getActiveContracts
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------

+------------------+--------------------+---------------------------------------------------------------------------------------------------------+---------------------------------+
|gRPC status code |gRPC status code |Remarks |Ledger API |
Expand All @@ -15,7 +15,7 @@ ActiveContractsService.getActiveContracts


CommandCompletionService.completionStream
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------

+------------------+--------------------+---------------------------------------------------------------------------------------------------------+---------------------------------+
|gRPC status code |gRPC status code |Remarks |Ledger API |
Expand All @@ -28,7 +28,7 @@ CommandCompletionService.completionStream


CommandService.submitAndWait
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------

+-------------------+------------------+------------------------------------------------------------------------------+-------------------------------+
|gRPC status code |gRPC status code |Remarks |Ledger API |
Expand All @@ -49,7 +49,7 @@ CommandService.submitAndWait


CommandService.submitAndWaitForTransaction
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------

+-------------------+------------------+------------------------------------------------------------------------------+-------------------------------+
|gRPC status code |gRPC status code |Remarks |Ledger API |
Expand All @@ -70,7 +70,7 @@ CommandService.submitAndWaitForTransaction


CommandService.submitAndWaitForTransactionId
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------

+-------------------+------------------+------------------------------------------------------------------------------+-------------------------------+
|gRPC status code |gRPC status code |Remarks |Ledger API |
Expand All @@ -91,7 +91,7 @@ CommandService.submitAndWaitForTransactionId


CommandService.submitAndWaitForTransactionTree
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------

+-------------------+------------------+------------------------------------------------------------------------------+-------------------------------+
|gRPC status code |gRPC status code |Remarks |Ledger API |
Expand All @@ -112,7 +112,7 @@ CommandService.submitAndWaitForTransactionTree


CommandSubmissionService.submit
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------

+------------------+-----------------+-------------------------------------------------------------------------+-------------------------------+
|gRPC status code |gRPC status code |Remarks |Ledger API |
Expand All @@ -123,7 +123,7 @@ CommandSubmissionService.submit


ConfigManagementService.setTimeModel
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------

+------------------+--------------------+----------------------------------------------------------------------------------+-------------------------------+
|gRPC status code |gRPC status code |Remarks |Ledger API |
Expand All @@ -138,7 +138,7 @@ ConfigManagementService.setTimeModel


GrpcHealthService.check
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------

+------------------+-----------------+----------------------------------------------------------------------------------------+-----------------+
|gRPC status code |gRPC status code |Remarks |Ledger API |
Expand All @@ -149,7 +149,7 @@ GrpcHealthService.check


GrpcHealthService.watch
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------

+------------------+-----------------+----------------------------------------------------------------------------------------+-----------------+
|gRPC status code |gRPC status code |Remarks |Ledger API |
Expand All @@ -160,7 +160,7 @@ GrpcHealthService.watch


PackageManagementService.uploadDarFile
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------

+------------------+--------------------+----------------------------------------------------------------------------+------------------------+
|gRPC status code |gRPC status code |Remarks |Ledger API |
Expand All @@ -175,7 +175,7 @@ PackageManagementService.uploadDarFile


ParticipantPruningService.prune
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------

+------------------+--------------------+-------------------------------------------------------------------------------------------------------+-----------------------+
|gRPC status code |gRPC status code |Remarks |Ledger API |
Expand All @@ -190,7 +190,7 @@ ParticipantPruningService.prune


PartyManagementService.allocateParty
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------

+------------------+------------------+-------------------------------------------------------------------+-----------------+
|gRPC status code |gRPC status code |Remarks |Ledger API |
Expand All @@ -201,7 +201,7 @@ PartyManagementService.allocateParty


SubmissionService.submit
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------

+------------------+--------------------+-------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
|gRPC status code |gRPC status code |Remarks |Ledger API |
Expand Down Expand Up @@ -236,7 +236,7 @@ SubmissionService.submit


TransactionService.getFlatTransactionByEventId
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------

+------------------+-----------------+----------------------------------------------------------------------------------------+-------------------+
|gRPC status code |gRPC status code |Remarks |Ledger API |
Expand All @@ -249,7 +249,7 @@ TransactionService.getFlatTransactionByEventId


TransactionService.getTransactionByEventId
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------

+------------------+-----------------+----------------------------------------------------------------------------------------+----------------------+
|gRPC status code |gRPC status code |Remarks |Ledger API |
Expand All @@ -264,7 +264,7 @@ TransactionService.getTransactionByEventId


TransactionService.getTransactionTrees
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------

+------------------+--------------------+---------------------------------------------------------------------------------------------------------+---------------------------------+
|gRPC status code |gRPC status code |Remarks |Ledger API |
Expand All @@ -283,7 +283,7 @@ TransactionService.getTransactionTrees


TransactionService.getTransactions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------------------------------------------------------------------

+------------------+--------------------+---------------------------------------------------------------------------------------------------------+---------------------------------+
|gRPC status code |gRPC status code |Remarks |Ledger API |
Expand Down
1 change: 1 addition & 0 deletions docs/source/app-dev/ledger-api.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ The Ledger API

services
grpc/index
grpc/error-codes
grpc/proto-docs
grpc/daml-to-ledger-api
daml-lf-translation
Expand Down
Loading

0 comments on commit 5f3a4d2

Please sign in to comment.