Success and Error Codes

Each Architect API returns an HTTP status code that indicates the result of the operation. Use this page to quickly diagnose client-side failures (4xx) across the Architect APIs. It lists the supported error codes, what they mean, common causes, and recommended fixes, plus example request patterns.

Standard Success Responses

Shared Error Envelope

All error responses follow a consistent JSON structure based on RFC 9457 (Problem Details):

{
    "type": "https://example.com/probs/error",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "System is overloaded, please try again later",
    "instance": "urn:atpco:error:architect:prod?trace-id=af4bc1cafcc833c3d478ddea2a8fc3d849199bc2",
    "timestamp": "2024-01-01T12:00:00.000Z",
    "retryable": true
}

Some APIs may return additional error information in an errors array. Each entry contains:

Error Catalog (4xx)

📝 Multiple error codes can share HTTP 400. They are distinct and point to different client issues.

Standard Server Error Responses

Rate Limiting

The Architect APIs include rate limiting headers in all responses:

API-Specific Examples

Subscriptions Times API

Endpoint: GET /substime

Typical 401 (Unauthorized)

{
    "type": "https://example.com/probs/unauthorized",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Invalid API Key",
    "instance": "urn:http:GET:/substime:f5966aeb-e3c1-4b30-9050-d9737c051b4f",
    "timestamp": "10/Feb/2026:16:38:54 +0000"
}

Cause: Missing or incorrect API Key in the header.

Fix: Provide the correct API key in the X-Api-Key header.

Blueprint API

Bad Request (400)

Typical Scenarios:

• Missing required fields in request body
• Invalid data format (e.g., invalid date format)
• Request body exceeds size limits
• Invalid query parameters

Example Response:

{
    "type": "https://example.com/probs/error",
    "title": "Bad Request",
    "status": 400,
    "detail": "Missing required field: hostCarrierCode",
    "instance": "urn:atpco:error:architect:prod?trace-id=af4bc1cafcc833c3d478ddea2a8fc3d849199bc2",
    "timestamp": "2024-01-01T12:00:00.000Z"
}

Resolution:

• Validate request payload against API specification
• Check required fields are present
• Verify data types and formats match schema requirements

Unprocessable Entity (422)

Typical Scenarios:

• Invalid data in Architect database (read use case)
• Invalid request body — well-formed but containing bad data (write use case)

Example Response:

{
    "type": "https://example.com/probs/error",
    "title": "Unprocessable Entity",
    "status": 422,
    "detail": "Unable to process condition 'fds_react'",
    "instance": "urn:atpco:error:architect:dev",
    "timestamp": "2025-11-07T02:47:18.388213Z",
    "retryable": false,
    "errors": [
        {
            "path": "data.content.rows[0].apply.fareAmount",
            "message": "Invalid cross-reference $priceExclTax",
            "value": "$priceExclTax"
        }
    ]
}

Resolution:

• Validate request payload against Architect validations (write use case)
• Validate Architect data (read use case) by calling Architect backend services directly

Too Many Requests (429) – Rate Limiting

Typical Scenarios:

• Exceeded API rate limits
• System overload protection
• Burst traffic patterns

Example Response:

{
    "type": "https://example.com/probs/error",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "System is overloaded, please try again later",
    "instance": "urn:atpco:error:architect:prod?trace-id=af4bc1cafcc833c3d478ddea2a8fc3d849199bc2",
    "timestamp": "2024-01-01T12:00:00.000Z",
    "retryable": true
}

Resolution:

• Implement exponential backoff retry strategy
• Check Retry-After header for wait time
• Reduce request frequency
• Consider request batching

Quick Troubleshooting Flow

1. Check HTTP status + code. Distinguish auth (401/403) from validation (400/422) and quota (429).
2. Read detail. It often pinpoints the exact field.
3. Confirm base URL/environment. Mis-pointing to prod/nonprod often causes 404/401.
4. Validate locally. Use the published OpenAPI schema or client SDK validators before retrying.
5. Retry policy. Do not retry 400/401/403/404/422 without fixing input; only backoff on 429 or transient 5xx.
6. Include instance when asking for help. Add timestamp, environment, and endpoint to support tickets.