Reference
Responses

Responses

This page documents the HTTP response codes, error response formats, and collection response structure for the Protime API.

Response codes summary

Verb Code Reason
Any 400 The query string or request body contains invalid input
401 Invalid or missing Bearer token
403 Valid Bearer token but the service does not have the required scope
404 The requested resource does not exist
414 URI too long (the server enforces a 4 096-character limit)
429 Too many requests (see rate limiting)
500 Internal server error
503 Service unavailable, e.g. during maintenance
GET 200 The request succeeded and the response body contains the requested data
304 The data has not changed since the last request (no body)
409 Concurrency conflict (collection endpoints with delta)
410 The delta token has expired and is no longer available
POST 201 A new resource has been created
PUT 200 An existing resource has been updated
201 A new resource has been created (upsert endpoints)
409 Concurrency conflict
DELETE 200 The resource has been deleted (body may be empty)
204 The resource has been deleted (no body)

Error response format

Most error responses (4xx, 5xx) wrap an error object inside an error property. The inner object always contains code and message fields.

{
    "error": {
        "code": "ErrorCode",
        "message": "Human-readable description"
    }
}

Controller validation errors

When a controller rejects a request because of invalid filter parameters or business rule violations, the response includes a reasons array inside the error wrapper:

{
    "error": {
        "code": "BadRequest",
        "message": "The request was invalid",
        "reasons": [
            "The provided date range is invalid"
        ]
    }
}

Model validation errors

When the request body fails model validation (for example, a required field is missing or the JSON cannot be deserialized), the API returns a BadRequest response without the error wrapper. The validationErrors array appears at the top level:

{
    "code": "BadRequest",
    "message": "The request was invalid",
    "validationErrors": [
        "SomeField is required"
    ]
}

If the request body cannot be deserialized at all, the validationErrors array contains a single entry:

{
    "code": "BadRequest",
    "message": "The request was invalid",
    "validationErrors": [
        "Cannot deserialize provided request to a valid JSON"
    ]
}

Common error codes

Code HTTP status Description
BadRequest 400 Invalid query parameters or request body
Unauthorized 401 Missing or invalid authentication token
NotFound 404 The requested resource does not exist
Conflict 409 A concurrency conflict occurred
Gone 410 The requested resource (e.g. a delta token) is no longer available
UriTooLong 414 The constructed URI exceeds the server limit
TooManyRequests 429 The request rate has been exceeded

Example: NotFound 

{
    "error": {
        "code": "NotFound",
        "message": "No data was found for the request"
    }
}

Collection response format

GET endpoints that return multiple resources use a collection envelope. The value array contains the resource objects. Null fields are omitted from the response.

{
    "value": [ ... ],
    "nextLink": "...?$continuationToken=abc",
    "deltaLink": "...?$deltaToken=xyz"
}
Field Type Description
value array The collection of resource objects
nextLink string or null A relative URI for the next page of results; absent when the current page is the last
deltaLink string or null A token URI for delta synchronization; absent when nextLink is present

Rate limiting

Application-level rate limiting is not currently active in the Protime API. The 429 Too Many Requests status code is declared in the API specification for forward compatibility, but no request-rate policies are enforced by the application at this time. Infrastructure-level rate limiting outside of this service may still apply.

If a 429 response is received, it indicates that an infrastructure-level throttle has been triggered. The response body follows the standard error format with code TooManyRequests.

See also

AuthenticationFiltering