Skip to main content
MedDRA Explorer uses the RFC 7807 “Problem Details” format for every non-success response. Each error shares the same envelope so SDKs can handle it generically, regardless of which endpoint triggered it.

​
Standard problem envelope

{
	"type": "https://docs.meddra.co/problems/{slug}",
	"title": "Human readable summary",
	"status": 400,
	"detail": "Optional explanation for operators.",
	"instance": "/codes?version=28.1",
	"code": "MACHINE_READABLE_CODE",
	"requestId": "req_3hZPp6EQ",
	"errors": {
		"field": ["Array of validation messages"]
	}
}
  • type points to public documentation of the error class.
  • title is a short human label; detail provides optional context.
  • code is a stable machine-readable identifier you can switch on in client code.
  • requestId helps support trace the failure. Pass it along in support tickets.
  • errors only appears on validation responses and is a map of field → message array.

​
400 – Validation errors

{
	"type": "https://docs.meddra.co/problems/validation",
	"title": "Validation error",
	"status": 400,
	"detail": "One or more request fields are invalid.",
	"code": "VALIDATION_ERROR",
	"requestId": "req_01JABCD123",
	"errors": {
		"version": ["Version 99.9 is not available"],
		"limit": ["Must be 200 or less"]
	}
}
  • Every invalid field is listed in errors.
  • Clients should read errors first, and then fall back to detail for a summary.

​
401 – Unauthorized

As we introduce API keys, unauthenticated calls will return: 
{
	"type": "https://docs.meddra.co/problems/unauthorized",
	"title": "Authentication required",
	"status": 401,
	"detail": "Provide a valid API key in the Authorization header.",
	"code": "UNAUTHORIZED",
	"requestId": "req_01JABCD999"
}
  • Ensure you include the correct Authorization header (for example, Bearer <API_KEY>).
  • Regenerate or rotate keys from the dashboard if you suspect a leak.

​
403 – Forbidden

When authentication succeeds but the key lacks access to the requested resource, the API will return: 
{
	"type": "https://docs.meddra.co/problems/forbidden",
	"title": "Forbidden",
	"status": 403,
	"detail": "Your API key cannot access this resource.",
	"code": "FORBIDDEN",
	"requestId": "req_01JABCDEF0"
}
  • Check the key’s permissions in the MedDRA dashboard.
  • Reach out to the workspace owner if you need the role upgraded.

​
429 – Rate limited

{
	"type": "https://docs.meddra.co/problems/rate-limit",
	"title": "Too many requests",
	"status": 429,
	"detail": "You have reached the per-minute request limit.",
	"code": "RATE_LIMITED",
	"requestId": "req_01JABCD456",
	"retryAfter": 15,
	"limit": 1000,
	"reset": "2025-01-10T12:34:56.000Z"
}
  • The HTTP response includes a Retry-After header (seconds until reset).
  • retryAfter, limit, and reset repeat the same values in the body for convenience.
  • Back off until the reset time and then retry.

​
500 – Internal errors

{
	"type": "https://docs.meddra.co/problems/internal",
	"title": "Internal server error",
	"status": 500,
	"detail": "An unexpected error occurred. Contact support with the requestId if the issue persists.",
	"code": "INTERNAL_ERROR",
	"requestId": "req_01JABCD789",
	"supportUrl": "https://docs.meddra.co/support"
}
  • We only return 500s for unexpected failures.
  • Provide the requestId when contacting support so we can trace the root cause quickly.

​
Handling guidelines

  • Always inspect status and code. They are stable across endpoints.
  • Surface detail to humans; parse errors for field-level feedback.
  • For retries, respect retryAfter and limit.
  • Log requestId so you can correlate user reports with our backend diagnostics.
⌘I