📘 Common HTTP Status Codes in the API

This document describes how certain HTTP status codes are used within the API and provides example responses in JSON format. For error responses, the API may return data in the Problem Details format or a variation of it (e.g., ProblemValidationDetails for validation issues).

✅ 200 OK

Meaning

Indicates that the request was successfully received, understood, and processed by the server. A 200 OK response usually contains the requested resource or relevant data.

Example Response

{
  "id": 123,
  "name": "Sample Resource",
  "description": "Details about the resource."
}

⏳ 202 Accepted

Meaning

The request has been accepted for processing, but the processing has not been completed yet. This status is often used for asynchronous or background operations.

Example Response

{
  "batchId": "abc123",
  "status": "PENDING"  
}

❌ 400 Bad Request

Meaning

The server could not process the request due to a client-side error (e.g., invalid JSON body, incorrect parameters, or failed validation rules).

Example Error (Validation Problem)

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Validation Error",
  "status": 400,
  "errors": {
    "LanguageCode": [
      "Language [en-GB] is not defined on the quest"
    ]
  },
  "traceId": "00-3881c297da8e75ac3d6a2c1cac7f5cc5-1f0f04ec1e099740-01",
  "requestId": "0HNBJ90A36SE6:00000002"
}

🔐 401 Unauthorized

Meaning

The request requires valid authentication credentials, but none were provided or they were invalid.

Example Error

{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Not authorized to access GET /v1/optout/.",
  "instance": "/v1/optout/",
  "traceId": "00-fb0c92441a3ebdc10a633217fcc4b44e-bc723a316358ce88-01",
  "requestId": "0HNBJG8D44GDV:00000004"
}

⛔ 403 Forbidden

Meaning

The client’s credentials are valid, but the user is not allowed to access the requested resource. This typically means insufficient permissions.

Example Error

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.4",
  "title": "Forbidden Resource",
  "status": 403,  
  "detail": "No access to the quest with id 0191c65c-7fb5-4d48-7a97-9216cae317a7",
  "traceId": "00-2c8162788967eafff83d84471a474586-aa35a03ad9a447c9-01",
  "requestId": "0HNBJ90A36SE7:00000001"
}

📭 404 Not Found

Meaning

The requested resource could not be found. This often occurs if the resource ID is incorrect or the endpoint path is invalid.

Example Error

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "The requested resource was not found.",
  "status": 404,
  "detail": "The endpoint GET /v1/quests/0191c65c-7fb5-4d48-7a97-5634cae317a6/NOTFOUND does not exist.",
  "traceId": "00-fa64e6ec07506d51f25c2c54066e58f7-338080fa3930b9dc-01",
  "requestId": "0HNBJ90A36SE8:00000001"
}

🪦 410 Gone

Meaning

The requested resource is no longer available and has been permanently removed. This status code is used to indicate that the resource will not be available again and no forwarding address is known. Clients should not retry the request.

This may occur, for example, if a previously generated export has been deleted.

Example Error

{
  "type": "https://datatracker.ietf.org/doc/html/rfc9110#name-410-gone",
  "title": "Gone",
  "status": 410,
  "detail": "The participant link you are trying to access is no longer available.",
  "traceId": "00-d86b99c61f364d778e178c73262c74b5-7ef0cdb98fc34670-01",
  "requestId": "0HNBJ90A36SE9:00000001"
}

🧨 429 Too Many Requests

Meaning

The client has sent too many requests in a short period of time and is being throttled.

Example Error

{
  "type": "https://yourapi.com/errors/too-many-requests",
  "title": "Too Many Requests",
  "status": 429,
  "traceId": "00-abc123def456...",
  "detail": "You have exceeded the request rate limit. Please wait before sending additional requests."
}

Look for rate-limiting headers to determine when you can retry:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

💥 500 Internal Server Error

Meaning

The server encountered an unexpected condition or unhandled exception.

Example Error

{
  "type": "Internal Error",
  "title": "Unhandled exeption",
  "status": 500,
  "detail": "Connection refused (unknown.host.internal:5184)",
  "traceId": "00-e433b23d12b6dca6fee32bb7426c2ca6-485956469b02f443-01",
  "requestId": "0HNBJFV5AP4AK:00000001"
}

📝 Notes

Content-Type
Error responses typically include the following header:
```
Content-Type: application/problem+json
```
Trace Identifier
The traceId field helps correlate requests to logs and traces in Questback. Please include this in any support inquiries.
ProblemValidationDetails
For validation errors, detailed human-readable messages are provided in the errors object.
Support
When contacting support, always include the full error response and traceId.

📄 Pagination And DateTime filtering

📅 DateTime Format