📘 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 OKCopied!

MeaningCopied!

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 AcceptedCopied!

MeaningCopied!

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 RequestCopied!

MeaningCopied!

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 UnauthorizedCopied!

MeaningCopied!

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 ForbiddenCopied!

MeaningCopied!

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 FoundCopied!

MeaningCopied!

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 GoneCopied!

MeaningCopied!

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 RequestsCopied!

MeaningCopied!

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 ErrorCopied!

MeaningCopied!

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"
}

📝 NotesCopied!

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.