使用PHP cURL调用POST JSON API返回500错误，该如何排查解决？

我正尝试通过PHP cURL在我的API中创建新客户，客户、产品等所有资源均通过POST方法创建，我的代码如下：

$json='{
"data": {
    "type": "customers",
    "attributes": {
        "tax_registration_number": "5555555550",
        "business_name": "Test customer",
        "contact_name": "Mr. Test",
        "website": "https://www.testurl.pt",
        "phone_number": "2299999999",
        "mobile_number": "9299999999",
        "email": "test@testcustomer.pt",
        "observations": "This is only a test",
        "internal_observations": "This is good customer",
        "not_final_customer": null,
        "cashed_vat": null,
        "tax_country_region": "PT-MA"
    },
    "relationships": {
        "main_address": {
            "data": {
                "type": "addresses",
                "id": 1
            }
        },
        "addresses": {
            "data": [
                {
                    "type": "addresses",
                    "id": 1
                },
                {
                    "type": "addresses",
                    "id": 2
                }
            ]
        }
    }
}
}';
 print($json);

以下是我初始化cURL的代码，我已经获取到token并完成了授权：

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,($url));
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,($json));
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/vnd.api+json',
    'Accept: application/json',
    'Authorization: Bearer ' . $token,
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
var_dump ($response);
$response=json_decode($response,true);
curl_close ($ch);

我收到的响应如下：

string(329) "{"errors":[{"status":"500 Internal Server Error","code":"JA006","detail":"Erro de sistema JA006: erro interno na base de dados. Por favor contacte o suporte técnico.","meta":{"internal-error":"in JsonapiJson::Value::operator[](ArrayIndex)const: requires arrayValue"}}],"jsonapi":{"version": "1.0","meta":{"libversion":"2.4.1"}}}"

请问有人可以帮我排查这个错误的原因吗？谢谢！

报错核心原因可从响应的内部错误信息定位：in JsonapiJson::Value::operator[](ArrayIndex)const: requires arrayValue，说明服务端解析请求JSON时，某段预期为数组的结构收到了非数组类型值，按以下优先级排查：

1. 停止手动拼接JSON字符串，改用PHP内置json_encode生成请求体。手动拼接JSON极易出现转义错误、语法遗漏，通过数组转JSON的方式可完全规避格式问题，示例如下：

$requestData = [
    'data' => [
        'type' => 'customers',
        'attributes' => [
            'tax_registration_number' => '5555555550',
            'business_name' => 'Test customer',
            'contact_name' => 'Mr. Test',
            'website' => 'https://www.testurl.pt',
            'phone_number' => '2299999999',
            'mobile_number' => '9299999999',
            'email' => 'test@testcustomer.pt',
            'observations' => 'This is only a test',
            'internal_observations' => 'This is good customer',
            // 按接口要求替换为对应类型有效值，不要直接传null
            'not_final_customer' => false,
            'cashed_vat' => false,
            'tax_country_region' => 'PT-MA'
        ],
        'relationships' => [
            'main_address' => [
                // 若接口要求main_address.data为数组，套一层数组结构即可
                'data' => [
                    ['type' => 'addresses', 'id' => '1']
                ]
            ],
            'addresses' => [
                'data' => [
                    ['type' => 'addresses', 'id' => '1'],
                    ['type' => 'addresses', 'id' => '2']
                ]
            ]
        ]
    ]
];
$json = json_encode($requestData, JSON_UNESCAPED_SLASHES|JSON_UNESCAPED_UNICODE);

2. 检查main_address字段结构：当前你传的main_address.data是单个对象，多数JSONAPI规范要求关联资源哪怕只有一个值也要用数组包裹，这是触发该报错的最常见原因。
3. 修正id字段类型：JSON:API规范要求所有资源id必须为字符串类型，你当前传的id是数字1、2，改为字符串"1"、"2"再测试。
4. 替换null值：not_final_customer和cashed_vat两个字段不要直接传null，对照接口文档确认字段类型后传入对应类型的有效值，null极易触发服务端类型校验失败。

内容的提问来源于stack exchange，提问作者Mariana Sousa