Overview

Dynamic Planner APIs follow consistent error-handling patterns to help your application diagnose failures, recover gracefully, and provide meaningful feedback to users. All endpoints use standard HTTP response codes, and errors are returned in a predictable JSON structure.

HTTP Status Codes

The API uses standard HTTP status codes to indicate whether a request succeeded or failed.

Successful Responses

• 200 OK — The request completed successfully.
• 201 Created — A resource was created.
• 204 No Content — Operation succeeded with no response body.

Client Error Responses

• 400 Bad Request — Invalid input or malformed request.
• 401 Unauthorized — Missing or invalid access token.
• 403 Forbidden — Token is valid but lacks permissions or scopes.
• 404 Not Found — Resource does not exist.
• 409 Conflict — Conflicting resource state.
• 429 Too Many Requests — Rate limit exceeded.

Server Error Responses

• 500 Internal Server Error — Unexpected error.
• 503 Service Unavailable — Temporary outage or maintenance.

Error Response Structure

All error responses follow a standard JSON format to help you diagnose issues effectively.

{
  "error": "InvalidRequest",
  "message": "The provided OrganisationUnitId is invalid.",
  "correlationId": "f31db8e7-25c4-4c02-8c88-fc8e0d9f56b3",
  "details": {
    "field": "organisationUnitId",
    "issue": "Value is not a valid GUID."
  }
}
            

Fields:

• error — Error category.
• message — Human‑readable description.
• correlationId — Unique identifier for tracing API calls.
• details — Optional structured information about validation issues.

Using Correlation IDs

Every error response includes a correlationId. Logging this value allows Dynamic Planner to diagnose issues quickly during support investigations and trace failures across distributed systems.

Including your own diagnostic identifier (e.g., x-dt-traceid) on outbound requests further enhances end‑to‑end observability.

Recommended Error Handling

To ensure a resilient integration, your application should:

• Log correlationId for diagnostics and support.
• Retry safely when receiving 429 or 503 responses.
• Handle validation failures (400) with user-friendly messages.
• Use idempotency patterns to prevent duplicate operations.
• Ensure tokens include the correct scopes to avoid 403 errors.

Retry Strategies

Not all errors warrant a retry. Retrying only when the API indicates a temporary condition ensures stability and prevents unnecessary load.

Retry for Temporary Errors Only

• 429 Too Many Requests — Rate limit reached; retry after backoff.
• 503 Service Unavailable — Temporary downtime or maintenance.
• 500 Internal Server Error — Retryable, but limit the number of attempts.

Use Exponential Backoff

Exponential backoff prevents retry storms and reduces pressure on the system. A recommended pattern is:

wait = baseDelay * 2^attempt
maxAttempts = 5

for attempt in 1..maxAttempts:
    send request
    if success: break
    if retryableError:
        sleep(wait)
    else:
        stop and surface error
            

Adding small randomised delays ("jitter") helps avoid simultaneous retries by multiple systems.

Fallback Strategies

For long-running or critical workflows, fallback paths ensure continuity without manual intervention.

Recommended Patterns

• Queue failed jobs and retry them after service recovery.
• Gracefully degrade user experiences rather than blocking workflows.
• Fail fast for non-retryable errors such as 400 or 403.
• Run health checks before executing large batches or synchronisations.

Example Error Scenarios

Recovering From a 503 Response

503 Service Unavailable
{
  "error": "ServiceUnavailable",
  "message": "The service is temporarily unavailable. Please retry."
}
            

Best practice: Retry using exponential backoff up to a maximum attempt limit.

Invalid Access Token

401 Unauthorized
{
  "error": "Unauthorized",
  "message": "Access token is missing or invalid."
}
            

Missing Required Field

400 Bad Request
{
  "error": "InvalidRequest",
  "message": "Required field 'clientId' was not provided."
}