github.com/fntlnz/docker@v1.9.0-rc3/errors/README.md (about)

     1  Docker 'errors' package
     2  =======================
     3  
     4  This package contains all of the error messages generated by the Docker
     5  engine that might be exposed via the Docker engine's REST API.
     6  
     7  Each top-level engine package will have its own file in this directory
     8  so that there's a clear grouping of errors, instead of just one big
     9  file. The errors for each package are defined here instead of within
    10  their respective package structure so that Docker CLI code that may need
    11  to import these error definition files will not need to know or understand
    12  the engine's package/directory structure. In other words, all they should
    13  need to do is import `.../docker/errors` and they will automatically
    14  pick up all Docker engine defined errors.  This also gives the engine
    15  developers the freedom to change the engine packaging structure (e.g. to
    16  CRUD packages) without worrying about breaking existing clients.
    17  
    18  These errors are defined using the 'errcode' package. The `errcode`  package
    19  allows for each error to be typed and include all information necessary to
    20  have further processing done on them if necessary.  In particular, each error
    21  includes:
    22  
    23  * Value - a unique string (in all caps) associated with this error.
    24  Typically, this string is the same name as the variable name of the error
    25  (w/o the `ErrorCode` text) but in all caps.
    26  
    27  * Message - the human readable sentence that will be displayed for this
    28  error. It can contain '%s' substitutions that allows for the code generating
    29  the error to specify values that will be inserted in the string prior to
    30  being displayed to the end-user. The `WithArgs()` function can be used to
    31  specify the insertion strings.  Note, the evaluation of the strings will be
    32  done at the time `WithArgs()` is called.
    33  
    34  * Description - additional human readable text to further explain the
    35  circumstances of the error situation.
    36  
    37  * HTTPStatusCode - when the error is returned back to a CLI, this value
    38  will be used to populate the HTTP status code. If not present the default
    39  value will be `StatusInternalServerError`, 500.
    40  
    41  Not all errors generated within the engine's executable will be propagated
    42  back to the engine's API layer. For example, it is expected that errors
    43  generated by vendored code (under `docker/vendor`) and packaged code
    44  (under `docker/pkg`) will be converted into errors defined by this package.
    45  
    46  When processing an errcode error, if you are looking for a particular
    47  error then you can do something like:
    48  
    49  ```
    50  import derr "github.com/docker/docker/errors"
    51  
    52  ...
    53  
    54  err := someFunc()
    55  if err.ErrorCode() == derr.ErrorCodeNoSuchContainer {
    56  	...
    57  }
    58  ```