Skip to main content

Response Status Codes

This guide explains the HTTP status codes you'll encounter when using MagicalAPI and how to handle them properly.

Common Status Codes​

StatusDescriptionExample Response
200Success - Request completed successfully{"data": {...}, "usage": {"credits": 10}}
400Bad Request - Invalid request format or subscription issues{"message": "Your request is invalid..."}
402Payment Required - Insufficient credits or plan restrictions{"message": "You don't have enough credits..."}
403Forbidden - Restricted route access{"message": "You can't access this service via api-key!"}
404Not Found - Resource not found{"message": "Service Not Found!"}
500Server Error - Internal service error or file processing issues{"message": "Internal server error!"}

Error Response Examples​

Bad Request (400)​

Invalid Request Format​

{
  "message": "Your request is invalid. request body should be a valid json."
}
{
  "message": "To access this service, you need to subscribe to this service from panel."
}
{
  "message": "This service is already subscribed."
}
{
  "message": "This service is already unsubscribed."
}

Payment Required (402)​

Insufficient Credits​

{
  "message": "You don't have enough credits to perform this action. Recharge your credits to proceed."
}

Plan Restrictions​

{
  "message": "API access not available for this plan. Please consider upgrading for access."
}

Forbidden (403)​

{
  "message": "You can't access this service via api-key!"
}

Not Found (404)​

Service Not Found​

{
  "message": "Service example_service with version 1.0 Not Found!"
}

Request Not Found​

{
  "message": "request id not found!"
}

Server Error (500)​

Internal Server Error​

{
  "message": "Internal server error!"
}

File Processing Errors​

{
  "message": "File format not Acceptable, only PDF, DOCX and DOC file supported."
}
{
  "message": "The provided file format does not match the expected MIME type. Please ensure they are correctly aligned."
}

Success Response Examples​

Initial Request (201)​

{
  "data": {
    "request_id": "abc123xyz"
  },
  "usage": {
    "credits": 10
  }
}

Final Response (200)​

{
  "data": {
    // Service-specific response data
  },
  "usage": {
    "credits": 10
  }
}
tip

Always check the usage.credits field in responses to track your credit consumption.