Error Messages

All error responses follow the standard envelope with a structured errors object. Error codes use the format MIDDAG-{DOMAIN}-{CODE} for domain-specific errors and standard API codes for transport-level errors.

API Error Codes

These codes appear in the errors.code field of any error response:

Code	HTTP	When	Example Detail
VALIDATION_ERROR	422	Invalid input fields	"Email is required"
AUTHENTICATION_ERROR	401	Missing, expired, or invalid token	"Token expired"
AUTHORIZATION_ERROR	403	Insufficient permissions	"Scope 'finances' required"
NOT_FOUND	404	Resource does not exist	"Organization 42 not found"
CONFLICT	409	Conflicting state	"Entitlement already cancelled"
RATE_LIMIT	429	Rate limit exceeded	"5 requests/min exceeded"
INTERNAL_ERROR	500	Unexpected server error	"Unexpected error"

Error Response Structure

{
    "success": false,
    "data": null,
    "meta": null,
    "message": "Validation failed",
    "errors": {
        "code": "VALIDATION_ERROR",
        "fields": {
            "email": [
                "Email is required"
            ],
            "name": [
                "Name must be at least 2 characters"
            ]
        }
    }
}

For non-validation errors, the errors object uses detail instead of fields:

{
    "success": false,
    "data": null,
    "meta": null,
    "message": "Authentication failed",
    "errors": {
        "code": "AUTHENTICATION_ERROR",
        "detail": "Token expired"
    }
}

Domain-Specific Error Codes

Organization Errors

Code	HTTP	Description
MIDDAG-ORG-NOT_FOUND	404	Organization does not exist
MIDDAG-ORG-CNPJ_INVALID	422	CNPJ failed federal API validation
MIDDAG-ORG-CNPJ_DUPLICATE	409	CNPJ already registered to another org
MIDDAG-ORG-DELETE_DENIED	403	Only the owner can delete an organization

Collaborator Errors

Code	HTTP	Description
MIDDAG-COLLAB-NOT_FOUND	404	Collaborator record not found
MIDDAG-COLLAB-INVITE_EXPIRED	409	Invite token has expired
MIDDAG-COLLAB-INVITE_USED	409	Invite already accepted or rejected
MIDDAG-COLLAB-ALREADY_MEMBER	409	User is already a collaborator
MIDDAG-COLLAB-ROLE_ESCALATION	403	Cannot assign a role higher than your own

Entitlement Errors

Code	HTTP	Description
MIDDAG-ENT-NOT_FOUND	404	Entitlement does not exist
MIDDAG-ENT-ALREADY_CANCELLED	409	Entitlement is already cancelled
MIDDAG-ENT-INVALID_TRANSITION	422	Status transition is not allowed
MIDDAG-ENT-INVALID_CLASS	422	Entitlement class is not recognized

Quote Errors

Code	HTTP	Description
MIDDAG-QUOTE-NOT_FOUND	404	Quote does not exist
MIDDAG-QUOTE-ALREADY_ACCEPTED	409	Quote was already accepted
MIDDAG-QUOTE-EXPIRED	409	Quote validity period has passed
MIDDAG-QUOTE-INVALID_TRANSITION	422	Status transition is not allowed

License Errors

Code	HTTP	Description
MIDDAG-LIC-NOT_FOUND	404	License does not exist
MIDDAG-LIC-UNAVAILABLE	503	License system is not available
MIDDAG-LIC-ACTIVATION_LIMIT	409	Maximum activations reached
MIDDAG-LIC-DOMAIN_REQUIRED	422	Domain parameter is required
MIDDAG-LIC-DOMAIN_NOT_ACTIVE	409	Domain is not currently activated

Service Errors

Code	HTTP	Description
MIDDAG-SVC-NOT_FOUND	404	Service does not exist
MIDDAG-SVC-INVALID_TRANSITION	422	Status transition is not allowed

Ticket Errors

Code	HTTP	Description
MIDDAG-SR-NOT_FOUND	404	Service request does not exist
MIDDAG-SR-INVALID_TRANSITION	422	Status transition is not allowed
MIDDAG-SR-ENV_ONLY	403	Clients can only create SRs for ENV entitlements

Authentication Errors

Code	HTTP	Description
MIDDAG-AUTH-INVALID_CREDS	401	Invalid email or password
MIDDAG-AUTH-TOKEN_EXPIRED	401	JWT has expired
MIDDAG-AUTH-TOKEN_REVOKED	401	Token revoked by logout
MIDDAG-AUTH-EMAIL_UNVERIFIED	403	Email not yet verified
MIDDAG-AUTH-ACCOUNT_DISABLED	403	Account has been disabled
MIDDAG-AUTH-RATE_LIMITED	429	Too many authentication attempts

Handling Errors in Client Code

const response = await fetch('/wp-json/middag-account/v1/entitlements', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'X-Middag-Organization': orgId,
  },
});

const body = await response.json();

if (!body.success) {
  if (body.errors.code === 'AUTHENTICATION_ERROR') {
    // Redirect to login or refresh token
  } else if (body.errors.code === 'VALIDATION_ERROR') {
    // Show field-level errors from body.errors.fields
  }
}

Related

• REST API Overview -- Error codes and envelope format
• Status Labels -- Valid status values to avoid CONFLICT errors