Bad Request

← Back to Overview

This error occurs when a request is structurally incorrect, requests an unsupported action, or violates schema write lifecycle rules (such as attempting to write a read-only field or modify an immutable property).

---

Generic Bad Request Example (RFC 9457)

{
  "type": "https://docs.apinow.app/errors/bad-request",
  "title": "Bad Request",
  "status": 400,
  "code": "INVALID_REQUEST",
  "detail": "Action 'archive' is not implemented for entity 'Invoice'.",
  "instance": "/api/v1/invoices/inv_99210/archive"
}

---

Write Lifecycle & Immutability Violations

When an API client violates property mutability or write constraints, the Serverless Engine rejects the request with 400 Bad Request and error code E_VALIDATION_ERROR:

Case 1: Client sends a readOnly field on POST (Create)

Read-only properties are system-managed (e.g., auto-increment sequences, timestamps, calculated metrics). API clients cannot supply them during creation:

{
  "type": "https://docs.apinow.app/errors/bad-request",
  "title": "Bad Request",
  "status": 400,
  "code": "E_VALIDATION_ERROR",
  "detail": "Property is read-only and cannot be set: created_at",
  "instance": "/api/v1/projects"
}

Case 2: Client modifies an immutable field on PUT or PATCH (Update)

Immutable properties can be assigned during creation (POST), but are permanently frozen thereafter:

{
  "type": "https://docs.apinow.app/errors/bad-request",
  "title": "Bad Request",
  "status": 400,
  "code": "E_VALIDATION_ERROR",
  "detail": "Property is immutable and cannot be modified after creation: key",
  "instance": "/api/v1/projects/MYPROJ"
}

Case 3: Client modifies a primary key on PUT or PATCH (Update)

A record’s primary identity cannot be updated in-place:

{
  "type": "https://docs.apinow.app/errors/bad-request",
  "title": "Bad Request",
  "status": 400,
  "code": "E_VALIDATION_ERROR",
  "detail": "Primary key cannot be modified: id",
  "instance": "/api/v1/products/42"
}

---

Troubleshooting Guide

For API Consumers (What it means & how to fix)

• Read-Only Fields on Create: Remove system-managed fields (such as id, created_at, updated_at, or created_by) from your POST request payload.
• Immutable Fields on Update: Do not attempt to alter write-once fields (such as natural project key, currency codes, or registration numbers) in PUT or PATCH requests.
• Idempotent Full PUT Requests: If your client sends the entire record back on PUT, make sure the immutable field contains the exact same value already stored in the database. The runtime permits identical value echoes, but strictly rejects changes.
• Primary Key Modifications: You cannot reassign a record’s primary key. If you need a new ID, create a new record via POST.
• Unsupported Actions: Verify the action name and HTTP method against the API’s OpenAPI specification.

For API Authors (Domain & API Modeler notes)

• Client-Assignable Keys: If you want API clients to supply custom identifiers on create (e.g., project key: "PROJ" or SKU), configure the property as Primary Key: true and Immutable: true in the Domain Modeler. Do not use Read-Only: true, as read-only strictly forbids all client writes.
• Action Exposures: Ensure that the action and HTTP method being requested are explicitly exposed in the API Modeler.
• Full Architecture Guide: Refer to Property Mutability & Write Lifecycle for complete specifications.