API Errors #
HTTP status codes 4xx
and 5xx
are errors.
The API returns a ServiceError
for every error response.
Service Errors #
A ServiceError
has the following schema:
{
"type": "AuthenticationError",
"code": "CredentialsInvalid",
"temporary": false,
"request_id": "sGH28YBJ"
}
type
describes the error category and can be one of the following values:
Fault
– a non-user errorAuthenticationError
– failure to provide sufficient credentialsValidationError
– failure to provide valid input valuesStateError
– the server state is inappropriate for the requested action
code
indicates the error cause and can be one of the following values:
ServerFailure
– a failure where there was an internal error at the serverSessionInvalid
– failure to provide valid session credentialsCredentialsInvalid
– failure to provide valid user credentialsValidationFailed
– failure to provide valid input valuesCodeOrganizationDoesNotExist
– failure to provide an existing organization nameCodeOrganizationAlreadyExists
– failure to provide an organization name that does not already existStageDoesNotExist
– failure to provide an existing stage nameStageAlreadyExists
– failure to provide a stage name that does not already existStageNameInvalid
- failure to provide a valid stage nameAppDoesNotExist
– failure to provide an existing app nameAppHasNoActiveRelease
- failure to provide an app with active releaseAppNameInvalid
- failure to provide a valid app nameReleaseDoesNotExist
- failure to provide an existing release id for an appAppAlreadyExists
– failure to provide an app name that does not already existServiceDoesNotExist
- failure to provide an existing service nameServiceAlreadyExists
- failure to provide a service name that does not already existServiceNameInvalid
- failure to provide a valid service nameNotificationNameInvalid
- failure to provide a valid notification nameChangesetDoesNotExist
– failure to request an operation on a non-existing changesetChangesetInvalid
– failure to validate the changeset, see fieldvalidation_errors
for an explanationCommitFailed
– failure to commit the changesetCommitAlreadyRunning
– requesting an operation on a changeset for which a commit is runningChangesetLocked
- caused by requesting an operation on a changeset that is locked by another operationCommitNotFound
– returned when trying to subscribe to a commit that is not currently runningTaskDoesNotExist
- failure to provide an existing task idCodeReleaseDigestInvalid
- failure to provide a valid release digestCodePermissionAlreadyExist
- adding permission for a user who already got permission for the stageCodePermissionDoesNotExist
- removing permission that does not exist for the StageCodeCantRemoveLastAdmin
- refusal to remove the last user with admin privileges for the stageCodeInsufficientPrivileges
- failure to have the correct privileges (e.g., admin privileges) for the operationCodeCurrentlyNotSupported
- returned when requesting an operation that is currently not supported by SetOpsCodeBackupNotFound
- returned when requesting an operation for a backup that doesn’t existOverload
– returned when the requested operation can currently not complete because the server is overloaded
temporary
indicates whether the fault is temporary and the client can retry the same request at a later time.
request_id
is a unique identifier for the request. This can be provided with support requests in order to help trace the request.
Validation Errors #
HTTP status code 422 Unprocessable Entity
is returned if the request is valid on a syntax level but the provided input parameters failed validation.
In this case, an additional field validation_errors
is returned:
{
"type": "ValidationError",
"code": "ValidationFailed",
"validation_errors": {
"name": ["too_short"]
},
"temporary": false,
"request_id": "mudkKnY7"
}
validation_errors
is an object. The keys correspond to request or response field names. The values are arrays of validator names. Those can be used to provide rich error messages to the user.
In case the field is an array, the key may include the index:
{
...
"validation_errors": {
"changeset": {
"commands[0]": ["taken"]
}
}
}
The following validators are returned:
invalid
: value is invalid (generic validation error, in case a more specific validator can’t be applied)invalid_format
: value has an invalid format, like a date is not provided in the correct formatrequired
: value can’t be blank (e.g. empty string)too_short
: value is too short (e.g. string of 3 characters where min 6 characters are expected)too_long
: value is too long (e.g. string of 10 characters where max 8 characters are expected)length_invalid
: value has the wrong length (e.g. string of 2 characters where a string of 3 to 8 characters is expected)greater_than_threshold
: value is greater than the threshold (e.g.8
where max is5
)greater_than_or_equal_to_threshold
: value is greater or equal to the threshold (e.g.5
where max is5
)greater_than_or_equal_to_dependent_value
: value is greater than or equal to a dependent value but must be smaller (e.g.5
where dependent value is3
)less_than_threshold
: value is lower than the threshold (e.g.-1
where min is0
)less_than_or_equal_to_threshold
: value is lower or equal to the threshold (e.g.0
where min is0
)less_than_or_equal_to_dependent_value
: value is less than or equal to a dependent value but must be greater (e.g.3
where dependent value is5
)not_an_integer
: value must be an integer, but isn’t (e.g.1.5
where an integer is expected)included
: value is included in the list of invalid values (e.g.a
wherea
,b
andc
are invalid)not_included
: value is not included in the list of allowed values (e.g.d
wherea
,b
andc
are supported)not_an_email_address
: value must be an email address, but isn’tmultiple_of_invalid
: value is expected to be a multiple of a specific valuetaken
: value is already taken (e.g. a stage namedawesome-production
already exists)not_found
: entity referenced can’t be found (e.g. an app namedweb
does not exist)stage_name_invalid
: value is not a valid stage nameapp_name_invalid
: value is not a valid app namerelease_digest_invalid
: value is not a valid release digestrelease_digest_does_not_exist
: value does not exist in image registry