Errors

Errors use standard HTTP status codes and one JSON shape, with a stable code you can branch on.

HTTP/1.1 400 Bad Request
X-Request-Id: req_5f0c1e2a9b7d4c3e8f6a1b2c

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "name: String must contain at least 1 character(s)",
    "param": "name",
    "request_id": "req_5f0c1e2a9b7d4c3e8f6a1b2c",
    "doc_url": "https://developer.v77trust.com/errors#validation_failed"
  }
}

Branch on error.code, not on message: messages are for people and may be reworded. type groups codes: authentication_error, permission_error, invalid_request_error, not_found_error, conflict_error, plan_limit_error, rate_limit_error, api_error.

Error codes

Code	Status	Meaning
`missing_api_key`	401	No Authorization header. Send Authorization: Bearer v77_…
`invalid_api_key`	401	The key is wrong or was revoked.
`insufficient_role`	403	The key's role can't do this. Use a key with the role shown in the reference.
`validation_failed`	400	A field is missing or invalid. param names the field.
`invalid_json`	400	The body isn't valid JSON.
`invalid_parameter`	400	A query parameter has a value that isn't allowed.
`parameter_missing`	400	A required query parameter is missing.
`invalid_limit`	400	limit must be 1–100.
`invalid_cursor`	400	cursor isn't a next_cursor value from this API.
`invalid_idempotency_key`	400	Idempotency-Key is longer than 255 characters.
`unknown_question`	400	An answers key isn't a classification question id.
`unknown_control`	400	No control with that code. See GET /controls.
`unknown_event`	400	Not a webhook event type. See GET /webhook-events.
`invalid_url`	400	Webhook URLs must be public HTTPS addresses.
`invalid_target`	400	The red-team target must be a public HTTPS address.
`plan_limit_reached`	402	Your plan's limit (e.g. number of high-risk systems or storage) is reached. kind, used and limit say which.
`resource_missing`	404	No object with that id in this workspace.
`not_classified`	404	The system has no classification yet (409 on endpoints that need one). Classify it first.
`no_assessment`	409	The system has no assessment. Classifying it opens one.
`idempotency_key_reused`	409	This Idempotency-Key was used for a different request.
`idempotency_in_progress`	409	A request with this Idempotency-Key is still running. Retry shortly.
`content_unavailable`	410	The evidence file is no longer stored.
`file_too_large`	413	Evidence files can be at most 25 MB.
`unsupported_media_type`	415	Evidence must be sent as multipart/form-data.
`evidence_required`	422	A control can't be marked implemented without evidence linked to it.
`rate_limited`	429	Too many requests. Wait Retry-After seconds.
`internal_error`	500	Something failed on our side. Retry with the same Idempotency-Key; contact us with the request_id if it persists.
`target_failed`	502	The model you asked us to red-team didn't respond.