Responses

Complete guide to all possible error responses from the Submit Form Response endpoint.

Success Response (201 Created)

json

{
	"success": true,
	"data": {
		"message": "Form response submitted successfully",
		"responseId": "uuid-string"
	},
	"timestamp": 1234567890
}

Error Responses

405 Method Not Allowed

json

{
	"success": false,
	"data": {
		"error": "Method not allowed. Only POST requests are accepted."
	},
	"timestamp": 1234567890
}

401 Unauthorized – Missing API Key

json

{
	"success": false,
	"data": {
		"error": "Missing API key. Please provide it in the X-API-Key header.",
		"parameter": "X-API-Key",
		"issue": "required but not provided"
	},
	"timestamp": 1234567890
}

Invalid API Key

json

{
	"success": false,
	"data": {
		"error": "API key validation failed: Invalid API key",
		"parameter": "X-API-Key",
		"issue": "invalid or expired"
	},
	"timestamp": 1234567890
}

400 Bad Request – Missing Form ID

json

{
	"success": false,
	"data": {
		"error": "Parameter 'formId' has invalid format: required but not provided or empty",
		"parameter": "formId",
		"issue": "required but not provided"
	},
	"timestamp": 1234567890
}

Invalid Field Responses

json

{
	"success": false,
	"data": {
		"error": "Parameter 'field_responses' has invalid format: required and must be an array",
		"parameter": "field_responses",
		"issue": "required and must be an array"
	},
	"timestamp": 1234567890
}

Missing Field ID

json

{
	"success": false,
	"data": {
		"error": "Parameter 'field_responses[n].field_id' has invalid format: required but not provided or empty",
		"parameter": "field_responses[n].field_id",
		"issue": "required but not provided"
	},
	"timestamp": 1234567890
}

Invalid Email Format

json

{
	"success": false,
	"data": {
		"error": "Parameter 'respondent.email' has invalid format: invalid email format. Expected format: user@domain.com",
		"parameter": "respondent.email",
		"issue": "invalid format"
	},
	"timestamp": 1234567890
}

Invalid URL Format

json

{
	"success": false,
	"data": {
		"error": "Parameter 'respondent.referrer_url' has invalid format: invalid URL format. Expected format: https://example.com",
		"parameter": "respondent.referrer_url",
		"issue": "invalid format"
	},
	"timestamp": 1234567890
}

Invalid IP Address

json

{
	"success": false,
	"data": {
		"error": "Parameter 'respondent.ip_address' has invalid format: invalid IP address format. Expected IPv4 (192.168.1.1) or IPv6 format",
		"parameter": "respondent.ip_address",
		"issue": "invalid format"
	},
	"timestamp": 1234567890
}

403 Forbidden – Unauthorized Form Access

json

{
	"success": false,
	"data": {
		"error": "Unauthorized: API key cannot access this form. Form does not belong to your organization.",
		"parameter": "formId",
		"issue": "form not accessible with provided API key"
	},
	"timestamp": 1234567890
}

500 Internal Server Error – General Server Error

json

{
	"success": false,
	"data": {
		"error": "Internal server error occurred while processing the request",
		"issue": "unexpected server error"
	},
	"timestamp": 1234567890
}