Errors

The Migrayt API uses standard HTTP status codes and returns consistent JSON error bodies.

Error Response Format

{
  "statusCode": 400,
  "message":    "Human-readable description of the error",
  "error":      "Bad Request"
}

For validation errors, message is an array:

{
  "statusCode": 400,
  "message": [
    "email must be a valid email",
    "password must be at least 8 characters"
  ],
  "error": "Bad Request"
}

HTTP Status Codes

Code	Meaning
`200`	Success
`201`	Created
`204`	Success, no content (DELETE)
`400`	Bad Request — invalid input
`401`	Unauthorized — missing or invalid token
`403`	Forbidden — valid token, insufficient permissions
`404`	Not Found — resource does not exist or belongs to another tenant
`409`	Conflict — resource already exists
`429`	Too Many Requests — rate limit exceeded
`502`	Bad Gateway — downstream service (ADO, Jira, AWS) returned an error
`500`	Internal Server Error — unexpected error; contact support

Common Error Messages

Authentication

Message	Resolution
`Invalid or expired access token`	Refresh your token via `POST /api/auth/refresh`
`No refresh token`	Log in again via `POST /api/auth/login`
`Invalid credentials`	Check email and password

Migrations

Message	Resolution
`Migration run {id} not found`	Check the run ID and ensure it belongs to your tenant
`Run {id} is not paused`	Can only resume a run with status `PAUSED`
`Could not start migration worker`	Infrastructure issue — retry in a few minutes; contact support if persists
`Token exchange failed`	ADO or Jira OAuth token is invalid or expired — reconnect the platform

Connectors

Message	Resolution
`ADO connection failed: 401`	PAT is expired or has insufficient permissions
`Jira connection failed: 403`	API token lacks Project Administrator role
`Project not found in ADO`	Check the organisation and project name spelling
`Jira project key not found`	Verify the project key in Jira settings

Rate Limit Headers

When rate-limited (429), the response includes:

Retry-After:         30
X-RateLimit-Limit:   10
X-RateLimit-Reset:   1720001234

Wait for Retry-After seconds before retrying.

Idempotency

POST /api/migrations/project/{projectId}/start is idempotent within a session. If a migration is already running for the project, the existing run is returned rather than starting a new one. This prevents accidental duplicate migrations if a request is retried.

Plugins Security Overview