Platform
Request validation rules
Turn rejected input into a useful correction before resubmitting. Field failures on /api/v1 use the shared 422 problem response, while malformed paths, operator filters, and SCIM have distinct formats.
On this page
Start here
Validation errors are feedback about a request the caller can change. This guide helps you separate malformed paths and unsupported values from field-level data errors, present useful messages, and confirm that a rejected request did not create partial state.
Before you begin
- The request schema for the endpoint you are calling
- A captured status code and full error body from a non-production test request
- Client-side access to the original field names and values after secrets are redacted
Put it into practice
-
Validate obvious constraints locally
Check required fields, lengths, UUID shapes, allowed enums, and absolute HTTP or HTTPS URLs before sending. Server validation remains authoritative.
-
Map the server response
For a 422 problem, read extra.errors as an object from field name to an array of messages. Handle operator path and filter failures as 400 responses, and parse SCIM errors separately.
-
Correct and resubmit
Show messages beside the matching fields, preserve unrelated user input, and send a new request only after correction. Do not retry unchanged validation failures.
Invalid input produces an actionable field message, valid input proceeds once, and your client does not confuse a malformed path, authorization failure, or SCIM response with a normal 422 document.
01 Account and agent registration
detailsUser fields
email is required, unique, at most 160 characters, and must contain @ with no spaces. name is optional on API registration: when omitted, register_via_api derives it from the email local part. When supplied, name is 2-120 characters. password is required, at least 12 characters, and at most 72 characters.
Operator UUID path parameters
Invalid UUID path parameters on operator routes fail as HTTP 400 via UUIDParams ("Invalid UUID path parameter"), not as a 422 extra.errors map.
Bootstrap fields
workspace_name and agent_name are required. Invalid bootstrap data returns 422 without creating a partial account or workspace.
02 Outbound destinations
detailsWebhook subscriptions
name and an absolute HTTP(S) url are required; event_types must contain at least one entry. A signing secret is generated when omitted. Production delivery applies the outbound URL policy described in Production readiness.
03 Validation error example
example{
"type": "https://robotscenter.net/problems/unprocessable-entity",
"title": "Unprocessable entity",
"status": 422,
"detail": "Validation failed",
"request_id": "req-abc123",
"extra": {
"errors": {
"password": ["should be at least 12 character(s)"]
}
}
}Troubleshooting
- There is no extra.errors map
- Check the status and API surface. Invalid UUIDs and operator filters commonly return 400, while SCIM uses application/scim+json.
- A webhook URL passes form checks but delivery fails
- Schema validation only establishes a valid absolute URL. Production outbound policy can still block unsafe schemes, redirects, or reserved destinations.