Error Handling

In case a request to our API fails, the return value of the endpoints follows standard HTTP status code conventions.

A detailed reason can be found in the response. Common codes indicating a client error are 400 BadRequest and 404 NotFound`.

To give some further information on the cause of the error, the API also returns a standardized error object in the response body.

1{
2    "code": "validation-failed",
3    "description": "The model sent in the request is invalid. See the validation errors for details.",
4    "link": "https://developers.awork.com/#response-types",
5    "details": [
6        "Some more details about the error can go here.",
7        "Or here."
8    ],
9    "validationErrors": [
10        {
11            "property": "Name",
12            "message": "'Name' should not be empty."
13        }
14    ]
15}
  • code: A unique identifier for the error.
  • description: A human-readable explanation for the cause of the error.
  • link: A link to the corresponding documentation.
  • details: Further explanations or hints on fixing the request.
  • validationErrors: If the model validation failed, all violations are listed here.

Error Codes

Error CodeDescription
workspaceid-missingThe request is missing a valid team id. Most likely, your token is invalid.
not-foundThe requested resource could not be located.
entity-archivedThe request tried to perform an operation with an archived entity.
duplication-violationA property that requires a unique value detected a duplication.
database-commitThe commit to the database failed. Your changes have not been committed!
concurrency-violationConcurrent processes changed data and created conflicts in the process.
date-dependencyTwo or more date values are in violation with each other (e.g. start date after due date).
date-out-of-rangeA single date value is not in its validity range (e.g. birth date in the future).
value-out-of-rangeA value is not in its defined range of validity (e.g. negative prices).
invalid-operationThe request would have caused an illegal data state.
invalid-modelThe body of the request is invalid or empty.
validation-failedThe model validation of the request failed.
server-errorAn internal error occurred.
already-exist-errorThe request adds an entity which already exists.
invalid-filter-or-orderThe request contains an invalid filter or sort statement.
illegal-property-transitionThe request would cause a value transition which is not allowed.
unauthorizedThe owner of the request has insufficient permissions.
invalid-batch-operationThe request for a batch operations is invalid.
deactivated-userThe request tried to perform an operation with a deactivated user.
request-body-too-largeThe uploaded file exceeds the allowed size limit.
insufficient-subscription-levelYour team does not have the required subscription level to use this feature. Upgrade to a higher plan.
insufficient-seatsYour team does not have enough remaining seats while trying to invite or activate users.

HTTP Status Codes

On each request to our API, you will receive a response with a HTTP status code that indicates if it was successful.

Success Status Codes

MethodStatus CodeDescription
GET200 OKIncluding the object(s)
POST200 OKIncluding the newly created object
POST202 AcceptedFor batch or background operations
POST204 NoContentFor business operations without a return value
PUT200 OKIncluding the updated object
DELETE204 NoContent

Error Status Codes

Status CodeDescription
400 BadRequestWhen the request model is invalid or the operation is not allowed
401 UnauthorizedWhen the requesting user is lacking the necessary permissions for the request
404 NotFoundWhen a requested resource does not exist