API Responses

Responses follow standard HTTP status codes. Successful responses return 2xx. Client errors return 4xx and server errors return 5xx. See the MDN HTTP Status documentation for a full reference.

Error format

All error responses follow RFC 9457 Problem Details for HTTP APIs.

General errors

{
  "type": "https://problems.omnisend.com/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "Segment '000000000000000000000001' not found.",
  "instance": "urn:omnisend:request:550e8400-e29b-41d4-a716-446655440000"
}

Field	Description
`type`	URI identifying the problem type
`title`	Short description of the error
`status`	HTTP status code
`detail`	Human-readable explanation of this specific occurrence
`instance`	Trace ID — include this when contacting support

Validation errors (400)

When input validation fails, the response includes an errors array with one entry per invalid field:

{
  "type": "https://problems.omnisend.com/validation-failed",
  "title": "Validation failed",
  "status": 400,
  "detail": "One or more fields are invalid.",
  "errors": [
    {
      "field": "name",
      "code": "required",
      "message": "Name is required"
    },
    {
      "field": "content.email.fromEmail",
      "code": "invalid_format",
      "message": "Must be a valid email address"
    }
  ]
}

All validation errors are returned at once — the API does not stop at the first failure.

Common status codes

Status	Meaning
`200 OK`	Request succeeded
`201 Created`	Resource created successfully
`204 No Content`	Request succeeded, no body returned
`400 Bad Request`	Invalid input — check the `errors` array
`401 Unauthorized`	Missing or invalid authentication
`403 Forbidden`	Insufficient permissions
`404 Not Found`	Resource does not exist
`409 Conflict`	Resource state prevents this action
`422 Unprocessable Entity`	Operation incompatible with this resource type
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Unexpected server error